home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 237_01 / graduser.doc < prev    next >
Encoding:
Text File  |  1987-07-28  |  181.5 KB  |  5,448 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                       GRAD Graphics Library User's Manual
  15.  
  16.                                  Version 1.1
  17.  
  18.  
  19.                         for IBM PC/XT/AT or compatibles
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.                                                        June 07, 1987
  36.  
  37.  
  38.                                                        By Conrad Kwok
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.                                Table of Contents
  57.  
  58.        
  59.        1   Introduction . . . . . . . . . . . . . . . . . . . . . .    1
  60.           1.1  General Information  . . . . . . . . . . . . . . . .    1
  61.           1.2  Licence  . . . . . . . . . . . . . . . . . . . . . .    2
  62.           1.3  Future Enhancements  . . . . . . . . . . . . . . . .    3
  63.        2   How to use GRAD  . . . . . . . . . . . . . . . . . . . .    4
  64.           2.1  Compile and Link . . . . . . . . . . . . . . . . . .    4
  65.           2.2  Interpretation . . . . . . . . . . . . . . . . . . .    6
  66.        3   The GRAD Frame . . . . . . . . . . . . . . . . . . . . .    7
  67.           3.1  Related Functions  . . . . . . . . . . . . . . . . .    7
  68.              3.1.1  CreateFrame . . . . . . . . . . . . . . . . . .    7
  69.              3.1.2  SelectFrame . . . . . . . . . . . . . . . . . .    8
  70.              3.1.3  RemvFrame . . . . . . . . . . . . . . . . . . .    8
  71.        4   Coordinate System  . . . . . . . . . . . . . . . . . . .   10
  72.           4.1  Physical Coordinate System . . . . . . . . . . . . .   10
  73.           4.2  Logical Coordinate System  . . . . . . . . . . . . .   10
  74.              4.2.1  Setting Origin  . . . . . . . . . . . . . . . .   10
  75.              4.2.2  Translation . . . . . . . . . . . . . . . . . .   11
  76.              4.2.3  Windowing . . . . . . . . . . . . . . . . . . .   11
  77.           4.3  Related Functions  . . . . . . . . . . . . . . . . .   11
  78.              4.3.1  SetOrg  . . . . . . . . . . . . . . . . . . . .   12
  79.              4.3.2  RelOrg  . . . . . . . . . . . . . . . . . . . .   12
  80.           4.4  Summary  . . . . . . . . . . . . . . . . . . . . . .   12
  81.        5   Setting Window . . . . . . . . . . . . . . . . . . . . .   13
  82.           5.1  Function Description . . . . . . . . . . . . . . . .   13
  83.              5.1.1  ResetWin  . . . . . . . . . . . . . . . . . . .   13
  84.              5.1.2  SetWin  . . . . . . . . . . . . . . . . . . . .   13
  85.           5.2  Example  . . . . . . . . . . . . . . . . . . . . . .   14
  86.        6   GRAD Environment . . . . . . . . . . . . . . . . . . . .   15
  87.           6.1  Functions Description  . . . . . . . . . . . . . . .   15
  88.              6.1.1  EnvSave . . . . . . . . . . . . . . . . . . . .   15
  89.              6.1.2  EnvRsto . . . . . . . . . . . . . . . . . . . .   16
  90.        7   Selection of Plot Type . . . . . . . . . . . . . . . . .   16
  91.           7.1  Related Function . . . . . . . . . . . . . . . . . .   17
  92.              7.1.1  PlotType  . . . . . . . . . . . . . . . . . . .   17
  93.        8   Dot Plotting and Line Drawing  . . . . . . . . . . . . .   18
  94.           8.1  Functions Description  . . . . . . . . . . . . . . .   18
  95.              8.1.1  Dot . . . . . . . . . . . . . . . . . . . . . .   18
  96.              8.1.2  SetStyle  . . . . . . . . . . . . . . . . . . .   18
  97.              8.1.3  HorzLine  . . . . . . . . . . . . . . . . . . .   19
  98.              8.1.4  VertLine  . . . . . . . . . . . . . . . . . . .   19
  99.           8.2  Efficiency Consideration . . . . . . . . . . . . . .   20
  100.        9   Circle, Ellipse and Arc  . . . . . . . . . . . . . . . .   21
  101.           9.1  Functions Description  . . . . . . . . . . . . . . .   21
  102.              9.1.1  Circle  . . . . . . . . . . . . . . . . . . . .   21
  103.              9.1.2  Ellipse . . . . . . . . . . . . . . . . . . . .   22
  104.              9.1.3  FillCircle  . . . . . . . . . . . . . . . . . .   22
  105.              9.1.4  FillEllipse . . . . . . . . . . . . . . . . . .   23
  106.              9.1.5  Arc1  . . . . . . . . . . . . . . . . . . . . .   23
  107.              9.1.6  Earc1 . . . . . . . . . . . . . . . . . . . . .   24
  108.              9.1.7  Arc2  . . . . . . . . . . . . . . . . . . . . .   25
  109.              9.1.8  Earc2 . . . . . . . . . . . . . . . . . . . . .   26
  110.              9.1.9  ArcPoint  . . . . . . . . . . . . . . . . . . .   27
  111.           9.2  Hints  . . . . . . . . . . . . . . . . . . . . . . .   27
  112.        10  4-connected Region Filling . . . . . . . . . . . . . . .   29
  113.           10.1  Functions Description . . . . . . . . . . . . . . .   29
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.              10.1.1  SolidFill  . . . . . . . . . . . . . . . . . .   29
  124.              10.1.2  PatternFill  . . . . . . . . . . . . . . . . .   30
  125.           10.2  Hints . . . . . . . . . . . . . . . . . . . . . . .   31
  126.        11  Text Characters Related Functions  . . . . . . . . . . .   32
  127.           Introduction  . . . . . . . . . . . . . . . . . . . . . .   32
  128.           11.1  Functions Description . . . . . . . . . . . . . . .   32
  129.              11.1.1  LoadFont . . . . . . . . . . . . . . . . . . .   32
  130.              11.1.2  SelectFont . . . . . . . . . . . . . . . . . .   33
  131.              11.1.3  RemvFont . . . . . . . . . . . . . . . . . . .   33
  132.              11.1.4  WriteStr . . . . . . . . . . . . . . . . . . .   34
  133.              11.1.5  ReadStr  . . . . . . . . . . . . . . . . . . .   36
  134.              11.1.6  NextXY . . . . . . . . . . . . . . . . . . . .   37
  135.        12  Block Operations . . . . . . . . . . . . . . . . . . . .   38
  136.           12.1  Function Description  . . . . . . . . . . . . . . .   38
  137.              12.1.1  BlockCopy  . . . . . . . . . . . . . . . . . .   38
  138.              12.1.2  BlockSave  . . . . . . . . . . . . . . . . . .   39
  139.              12.1.3  BlockLoad  . . . . . . . . . . . . . . . . . .   39
  140.        13  Frame Printing . . . . . . . . . . . . . . . . . . . . .   41
  141.           13.1  Function Description  . . . . . . . . . . . . . . .   41
  142.              13.1.1  PrintFrame . . . . . . . . . . . . . . . . . .   41
  143.        14  The DRAW function  . . . . . . . . . . . . . . . . . . .   44
  144.           14.1  Draw  . . . . . . . . . . . . . . . . . . . . . . .   44
  145.        15  Miscellaneous Functions  . . . . . . . . . . . . . . . .   48
  146.           15.1  Functions Description . . . . . . . . . . . . . . .   48
  147.              15.1.1  GRADinit . . . . . . . . . . . . . . . . . . .   48
  148.              15.1.2  cleanup  . . . . . . . . . . . . . . . . . . .   48
  149.              15.1.3  XHLine . . . . . . . . . . . . . . . . . . . .   49
  150.              15.1.4  writec . . . . . . . . . . . . . . . . . . . .   49
  151.        16  Advance Functions  . . . . . . . . . . . . . . . . . . .   51
  152.           16.1  Functions Description . . . . . . . . . . . . . . .   51
  153.              16.1.1  calcaddr . . . . . . . . . . . . . . . . . . .   51
  154.              16.1.2  exchange . . . . . . . . . . . . . . . . . . .   51
  155.              16.1.3  fr_read  . . . . . . . . . . . . . . . . . . .   52
  156.              16.1.4  fr_write . . . . . . . . . . . . . . . . . . .   52
  157.              16.1.5  phyaddr  . . . . . . . . . . . . . . . . . . .   52
  158.              16.1.6  writetype  . . . . . . . . . . . . . . . . . .   53
  159.        17  System Dependent Functions . . . . . . . . . . . . . . .   54
  160.           17.1  Functions Description . . . . . . . . . . . . . . .   54
  161.              17.1.1  settext  . . . . . . . . . . . . . . . . . . .   54
  162.              17.1.2  setgraph . . . . . . . . . . . . . . . . . . .   54
  163.              17.1.3  initjlsr . . . . . . . . . . . . . . . . . . .   54
  164.              17.1.4  cleanjlsr  . . . . . . . . . . . . . . . . . .   55
  165.              17.1.5  dumpjlsr . . . . . . . . . . . . . . . . . . .   55
  166.        18  GRAD Global Variables  . . . . . . . . . . . . . . . . .   56
  167.           18.1  TEN_MS  . . . . . . . . . . . . . . . . . . . . . .   56
  168.           18.2  DOTVALUE  . . . . . . . . . . . . . . . . . . . . .   56
  169.           18.3  PRE_GRAD_ERR_LEVEL, POST_GRAD_ERR_LEVEL . . . . . .   56
  170.           18.4  PRE_ERROR_FUNC, POST_ERROR_FUNC . . . . . . . . . .   56
  171.           18.5  SPACING_FUNC  . . . . . . . . . . . . . . . . . . .   57
  172.           18.6  XLIMIT, YLIMIT  . . . . . . . . . . . . . . . . . .   57
  173.           18.7  ORGX, ORGY  . . . . . . . . . . . . . . . . . . . .   57
  174.           18.8  WINX1, WINX2, WINY1, WINY2  . . . . . . . . . . . .   58
  175.        19  Advance Topics . . . . . . . . . . . . . . . . . . . . .   59
  176.           19.1  Error Handling  . . . . . . . . . . . . . . . . . .   59
  177.           19.2  Using SPACING_FUNC  . . . . . . . . . . . . . . . .   60
  178.        20  Sample Programs  . . . . . . . . . . . . . . . . . . . .   62
  179.           20.1  MPrint and Interp . . . . . . . . . . . . . . . . .   62
  180.           20.2  Rotate  . . . . . . . . . . . . . . . . . . . . . .   63
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.           20.3  Size  . . . . . . . . . . . . . . . . . . . . . . .   64
  191.           20.4  DispFont  . . . . . . . . . . . . . . . . . . . . .   64
  192.           20.5  SwPrt (Sideway) . . . . . . . . . . . . . . . . . .   64
  193.           20.6  Tex2GRAD  . . . . . . . . . . . . . . . . . . . . .   65
  194.        Appendix A : Customizing of Printer Control Codes  . . . . .   67
  195.           General Information . . . . . . . . . . . . . . . . . . .   67
  196.           EPSON FX-80 Driver Case Study . . . . . . . . . . . . . .   69
  197.           OKI ML192 Driver Case Study . . . . . . . . . . . . . . .   69
  198.           Additional Information  . . . . . . . . . . . . . . . . .   70
  199.        Appendix B : Customizing of Output Device  . . . . . . . . .   71
  200.        Appendix C : Font File Structure . . . . . . . . . . . . . .   72
  201.           Fixed Size Character (type 0) . . . . . . . . . . . . . .   72
  202.           Variable Size Character (type 1)  . . . . . . . . . . . .   73
  203.        Appendix D : Block File Structure  . . . . . . . . . . . . .   74
  204.        Appendix E : Functions Summary . . . . . . . . . . . . . . .   75
  205.        Appendix F : System Limits . . . . . . . . . . . . . . . . .   76
  206.           Program Limits  . . . . . . . . . . . . . . . . . . . . .   76
  207.           Configuration Limits  . . . . . . . . . . . . . . . . . .   76
  208.        Appendix G : Error Messages  . . . . . . . . . . . . . . . .   78
  209.        Appendix H : List of Header Files  . . . . . . . . . . . . .   79
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.        GRAD User's Manual                                    June 7, 1987
  256.  
  257.        1   Introduction
  258.  
  259.        1.1  General Information
  260.  
  261.             GRAD  is a  graphics functions library  for program compiled
  262.        with Microsoft  C  compiler  V4.0  in  small  model.  The library
  263.        contains most  functions  you  normally  expected  in  a graphics
  264.        library plus a number of unique features.
  265.             
  266.             This  brief summary is  to  introduce  you  features in GRAD
  267.        version 1.1. Each of these features is described in detail in the
  268.        documentation.
  269.             
  270.          a. GRAD  supports  color graphics  card  in 640  X 200 graphics
  271.             mode,  Hercules 720  X 348  graphics mode and JLASER (2560 X
  272.             3162). Other output device can be configured.
  273.          
  274.          b. It can create multiple  virtual screens of  very large size.
  275.             which  is  limited by  memory.  That  means  you  can create
  276.             graphics even you do not have a graphics display screen.
  277.          
  278.          c. Functions are provided to maintain windows.
  279.          
  280.          d. Nearly all  low  level  functions  are  written  in assembly
  281.             language to provide speed.  The result below  is obtained by
  282.             running the program BRENCH on an AT compatible (8MHz, 1 wait
  283.             state). All library functions when compiled with Microsoft C
  284.             compiler  use   8088   codes  option.   All   times  are  in
  285.             millisecond.
  286.          
  287.                                  Hercules Card         Virtual Screen
  288.             a loop                  0.0023               0.0023
  289.             Horizontal Line         0.38                 0.27
  290.              (length 300)
  291.             Horiz. Line width 20    6.2                  4.3
  292.             Vertical Line           8.5                  5.7
  293.              (length 300)
  294.             Vert. Line width 2      8.5                  5.7
  295.             Vert. Line width 32    17.0                 11.3
  296.             Circle radius 100      25.5                 28.3
  297.             Ellipse both axes
  298.                is 100 pixels       30.5                 33.3
  299.             
  300.             When drawing a horizontal line, it takes about 1 microsecond
  301.             per pixel on average!
  302.             
  303.          e. The  whole   library  use  integer   arithmetic  only.  This
  304.             guarantees  high speed operations when executed without math
  305.             coprocessor and keep the program size small.
  306.          
  307.          f. Besides simple functions such as dot,  line, circle, ellipse
  308.             ...etc., high speed arc drawing and region filling functions
  309.             are also included.
  310.          
  311.          g. Screen  printing is provided  as standard  function in GRAD.
  312.             Many  different  options  are  provided  such  as  different
  313.             printing density and mixed printing of text and graphics.
  314.          
  315.  
  316.                                       - 1 -
  317.  
  318.  
  319.  
  320.  
  321.  
  322.        GRAD User's Manual                                    June 7, 1987
  323.  
  324.          h. GRAD provides functions for high speed and high quality text
  325.             display.
  326.          
  327.          i. The whole screen or part of a screen can be saved, loaded or
  328.             copied.
  329.          
  330.             
  331.             Several sample  programs  with practical  value are included
  332.        such as  sideway printing  and text  and graphics  merge printing
  333.        programs.
  334.  
  335.        
  336.        1.2  Licence
  337.  
  338.             You may freely  copy  and distribute  the  GRAD  library and
  339.        related programs provided that:
  340.          
  341.          a. The  whole  library  and  supporting  files   including  the
  342.             documentation and sample  programs  are not modified  in any
  343.             way.  However,  you  may modify  those  source  programs and
  344.             include them in the distribution in addition to the original
  345.             one.  For  example,  you have writen a driver  for different
  346.             graphics  display  card  or  different   printer,   you  are
  347.             encouraged to include that in the distribution and also send
  348.             a copy  to  me  such  that  I may include  that  in standard
  349.             distribution when next version is available.
  350.          
  351.          b. No price or other consideration is charged.  However a small
  352.             distribution cost may be charged for the cost  of  the disk,
  353.             shipping and handling.
  354.          
  355.             
  356.             You may freely distribute your programs containing  the GRAD
  357.        library code provided that:
  358.          
  359.          a. The   following   message   is  included  in   your  program
  360.             documentation.
  361.                This program  contains codes from the  GRAD graphics
  362.                library written by Conrad Kwok.  GRAD library can be
  363.                obtained by downloading from  BBS or  by sending $15
  364.                to the address below:
  365.               
  366.                        Mr. Conrad Kwok
  367.                        9228 Vancouver Drive
  368.                        Sacramento, CA 95826            
  369.          
  370.          b. The program must  be  in  public domain or  a user supported
  371.             program.
  372.          
  373.  
  374.        If your program does  not meet  the above requirements,  you must
  375.        get my  written  permission  prior  to  the  distribution  of you
  376.        program(s).
  377.  
  378.             If you find this library and the related  programs useful, a
  379.        contribution of  $20  or whatever  you  think  it  worth  will be
  380.        appreciated.  With  each  contribution  of $20  or more, one will
  381.        receives next major update of the library.
  382.  
  383.                                       - 2 -
  384.  
  385.  
  386.  
  387.  
  388.  
  389.        GRAD User's Manual                                    June 7, 1987
  390.  
  391.             
  392.             With  the contribution  of  $60  or more,  you  can  get the
  393.        commented source code of the latest version of GRAD library and a
  394.        programmer  reference  containing  information  of  the  internal
  395.        structure and  algorithms used.  The source code is  written in C
  396.        and  8088  assembly language.  The source code is copyrighted and
  397.        you are not allowed to distribute the source code in any form.
  398.             
  399.             Please send your contribution,  comments and suggests to the
  400.        address below:
  401.               
  402.                        Mr. Conrad Kwok
  403.                        9228 Vancouver Drive
  404.                        Sacramento, CA 95826            
  405.  
  406.        
  407.        1.3  Future Enhancements
  408.  
  409.        a. PatternFill will be enhanced to fill any 4-Connected Regions.
  410.  
  411.        b. PatternFill will accept pattern larger than 16 by 16 pixels.
  412.  
  413.        c. 80286 option will be provided.
  414.  
  415.        d. Increase speed of characters writing.
  416.  
  417.        e. Supports Medium Model (Multi Code segment and 64K data).
  418.  
  419.        f. More functions!
  420.  
  421.        g. Of course, also your comments and suggestions.
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.                                       - 3 -
  451.  
  452.  
  453.  
  454.  
  455.  
  456.        GRAD User's Manual                                    June 7, 1987
  457.  
  458.        2   How to use GRAD
  459.  
  460.             There are two ways to use the GRAD functions. The obvious is
  461.        to write a program that use  the GRAD functions  and then compile
  462.        and  link  with  GRAD  library.  Another way is  to  write a GRAD
  463.        command file that call GRAD  functions using syntax  similar to C
  464.        function call.  Then use the supplied program interp or Mprint to
  465.        interpret the file.
  466.             
  467.             The first way (compile and link) requires longer time but it
  468.        may use the full power of  C and GRAD  functions.  The second way
  469.        (interpretation)  limits the user to simple  graphics drawing but
  470.        the advantage is no compilation  and link is necessary.  Hence it
  471.        is good for simple drawings and debug a  drawing before including
  472.        in the final C program.
  473.             
  474.             The compile and link method will  be described  in detail in
  475.        this chapter.  The interpretation  method  will only be described
  476.        briefly in the chapter.  Details can be found in the user's guide
  477.        for interp and Mprint in the later chapter.
  478.             
  479.             Before we go on and try the first example,  I  want  to tell
  480.        you if you don't like to see any error message (in  text  form or
  481.        in bit mapped  form)  when the program is  in  graphics mode, you
  482.        want redirect  the output  from the file to  any file  you like.
  483.  
  484.        
  485.        2.1  Compile and Link
  486.  
  487.                
  488.                Knowledge of Microsoft C compiler Version  4.0 is
  489.                assumed and small model library must be installed
  490.                
  491.                
  492.             Below is a very  simple program  that draws a  dot only. Use
  493.        your  favorite  editor  to enter  the program below and  name the
  494.        program as "onedot.c".
  495.             
  496.                #include <stdio.h>
  497.                
  498.                main ()
  499.                {
  500.                        GradInit();     /* (1) */
  501.                        setgraph();     /* (2) */
  502.                        Dot(100,100);   /* (3) */
  503.                        getch();        /* (4) */
  504.                        settext();      /* (5) */
  505.                        cleanup(0);     /* (6) */
  506.                }
  507.  
  508.             Then compile and link the program using the command line:
  509.                cl /AS /J onedot.c /link GRADLIB
  510.             
  511.             If  you don't have  any typing  mistakes  and GRADLIB  is in
  512.        current  directory or  in  the  directory  specified  in  the LIB
  513.        environment variable,  you should get the file onedot.exe without
  514.  
  515.  
  516.  
  517.                                       - 4 -
  518.  
  519.  
  520.  
  521.  
  522.  
  523.        GRAD User's Manual                                    June 7, 1987
  524.  
  525.        getting an error message. If you get any error, go back and check
  526.        the program and make sure that the GRADLIB is properly installed.
  527.        Otherwise, you may go ahead and execute the program "onedot.exe".
  528.             
  529.             About one to two seconds  later,  the screen will be cleared
  530.        and you should find a single dot. Pressing any key will terminate
  531.        the program and the screen will return to text mode.
  532.             
  533.             Using the  GRAD library is simple.  Now let's  return to the
  534.        source listing and  examine it line by  line.  In the program, we
  535.        called 3  GRAD functions and 2 system dependent functions and 1 C
  536.        library function.
  537.  
  538.        (1) GRADinit is to initialize  the GRAD environment.  Now it only
  539.            performs a processor speed test and assign the result  to the
  540.            global  variable  TEN_MS.  Time  dependent  functions  may do
  541.            adjustment according to the  its value such  that they behave
  542.            the same on different speed computers. Actually we don't need
  543.            GRADinit in this case but  we should always  include that for
  544.            future compatibility.
  545.  
  546.        (2) setgraph is  not  a  standard  GRAD  function.  It  is system
  547.            dependent function.  It is only necessary if you  want to use
  548.            the default configured  graphics  screen.  Its function is to
  549.            change the display mode to graphics and clear the screen.
  550.  
  551.        (3) Dot is a GRAD function that  plot a  single dot. Dot(100,100)
  552.            means plot a dot at coordinate (100,100).
  553.  
  554.        (4) getch is a C library function that reads the next key pressed
  555.            on the keyboard.
  556.  
  557.        (5) settext  again is not a standard GRAD function. It is used to
  558.            change the display mode back to text mode.
  559.  
  560.        (6) cleanup is contrary to  GRADinit.  It should be called before
  561.            exit.  If the parameter to cleanup is  non-zero, cleanup will
  562.            execute  exit  with  the  parameter  as  exit  code.  If  the
  563.            parameter is zero, it will return to the caller.
  564.  
  565.        
  566.             Instead of using command line to do compile and link, we can
  567.        also use make file to do the same job. Below is an example:
  568.             
  569.                OPTIMIZE=/Ox
  570.                OPTIONS=/AS /J $(OPTIMIZE)
  571.                
  572.                .asm.obj:
  573.                        masm /ML $*;
  574.                
  575.                .c.obj:
  576.                        msc $(OPTION) $*;
  577.                
  578.                onedot.obj:     onedot.c
  579.                
  580.                onedot.exe:     onedot.obj
  581.                        link onedot,onedot,nul,GRADLIB;
  582.  
  583.  
  584.                                       - 5 -
  585.  
  586.  
  587.  
  588.  
  589.  
  590.        GRAD User's Manual                                    June 7, 1987
  591.  
  592.        2.2  Interpretation
  593.  
  594.             The one line  file  below will  perform exactly the  same as
  595.        our "onedot"  program in  the last  section  by  using  interp to
  596.        interpret it.
  597.             
  598.                Dot(100,100);
  599.             
  600.        Let's suppose the file above is called "onedot.gcm". To interpret
  601.        the file by interp, type
  602.  
  603.                interp onedot.gcm
  604.  
  605.        The syntax required by interp is described in a later chapter. 
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.                                       - 6 -
  652.  
  653.  
  654.  
  655.  
  656.  
  657.        GRAD User's Manual                                    June 7, 1987
  658.  
  659.        3   The GRAD Frame
  660.  
  661.             A frame is a memory area where the graphics image is stored.
  662.        It can be  any size  (there  are some  limitations and  they will
  663.        discuss in next section) but it must be an rectangle. Each bit of
  664.        the memory corresponds to a pixel.  The memory area  can be video
  665.        memory or  computer  working memory.  If it is video  memory, the
  666.        graphics image can be  seen on screen.  If it  is working memory,
  667.        the frame becomes a  virtual graphics screen.  The graphics image
  668.        can  only  be seen by  dumping  to the printer or  copying to the
  669.        video memory.
  670.             
  671.             More  than one  frame can exist simultaneously  within GRAD.
  672.        However  only one  frame can be  active at one time.  Usually the
  673.        graphics video memory is predefined  as the first  frame and this
  674.        is the default active frame. It is a permanent frame so it cannot
  675.        be removed by GRAD function RemvFrame which will be  described in
  676.        next section also.
  677.             
  678.             If you are the first time reading this manual,  you may skip
  679.        over this chapter and consider the video memory as the only frame
  680.        available. All functions that apply to the video memory frame can
  681.        be applied to the other frames in the same way.
  682.  
  683.        
  684.        3.1  Related Functions
  685.  
  686.        3.1.1  CreateFrame
  687.  
  688.                frame_number=CreateFrame(horizontal,vertical);
  689.                int frame_number, horizontal, vertical;
  690.  
  691.        RETURN VALUE
  692.             A frame number.
  693.  
  694.        DESCRIPTION
  695.  
  696.             The  CreateFrame  function  will  create  a  frame  of  size
  697.        specified by  the two parameters.  However,  the  horizontal size
  698.        must be an integral multiply of 16.  If it is not, the horizontal
  699.        size will be rounded up.
  700.             
  701.             Note that the maximum physical coordinate number will be one
  702.        less than the actual size because coordinate number starts at 0.
  703.  
  704.        POSSIBLE ERROR CONDITION
  705.  
  706.        a. Insufficient Memory
  707.           Program will terminate.
  708.           
  709.        b. Too many frame exist
  710.           The maximum number of frame allowed is an system parameter. If
  711.           the number is exceed, the program will terminate.
  712.           
  713.           
  714.        EXAMPLE
  715.  
  716.                frame=CreateFrame(640,200);
  717.  
  718.                                       - 7 -
  719.  
  720.  
  721.  
  722.  
  723.  
  724.        GRAD User's Manual                                    June 7, 1987
  725.  
  726.  
  727.        FUNCTIONS INCLUDED
  728.  
  729.                RemvFrame
  730.  
  731.        
  732.        3.1.2  SelectFrame
  733.  
  734.                ret=SelectFrame(frame);
  735.                int ret, frame;
  736.  
  737.        RETURN VALUE
  738.  
  739.             It  will  return  the active  frame number  just  before the
  740.        execution of SelectFrame if frame  number given is valid  and the
  741.        frame exist.  Otherwise -1  will be returned and the active frame
  742.        is not changed.
  743.             
  744.        DESCRIPTION
  745.             
  746.             The function  SelectFrame select  the current  active frame.
  747.        Furthermore, the drawing window and point of origin will reset to
  748.        the same as last time when the frame is deselected.  If the frame
  749.        is the first time selected after it  is created,  the origin will
  750.        be physical coordinate (0,0)  and the window size is same  as the
  751.        frame size.
  752.             
  753.        EXAMPLE
  754.  
  755.                if ((old_frame=SelectFrame(frame))==(-1))
  756.                        printf("Frame does not exist\n");
  757.                  .   .   .
  758.                  .   .   .   Draw in the new frame
  759.                  .   .   .
  760.                SelectFrame(old_frame);  /* switch back to the */
  761.                                         /* original frame     */
  762.  
  763.        FUNCTIONS INCLUDED
  764.  
  765.                SelectFont
  766.  
  767.        
  768.        3.1.3  RemvFrame
  769.  
  770.                ret=RemvFrame(frame);
  771.                int ret, frame;
  772.  
  773.        RETURN VALUE
  774.  
  775.             A return value of 0  means successful.  A return value of -1
  776.        means the frame does not exist. If the frame type is permanent, 0
  777.        will be returned but the frame can still be selected.
  778.  
  779.        DESCRIPTION
  780.  
  781.             The function RemvFrame will remove the frame  from GRAD. The
  782.        memory occupied by the frame will be deallocated.
  783.             
  784.  
  785.                                       - 8 -
  786.  
  787.  
  788.  
  789.  
  790.  
  791.        GRAD User's Manual                                    June 7, 1987
  792.  
  793.        EXAMPLE
  794.  
  795.                If (RemvFrame(frame)==(-1))
  796.                        printf("Frame does not exist\n");
  797.  
  798.        FUNCTIONS INCLUDED
  799.  
  800.                CreateFrame
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.                                       - 9 -
  853.  
  854.  
  855.  
  856.  
  857.  
  858.        GRAD User's Manual                                    June 7, 1987
  859.  
  860.        4   Coordinate System
  861.  
  862.        4.1  Physical Coordinate System
  863.  
  864.             Each Frame can be viewed as a two dimensional plane composes
  865.        of identical rectangular pixels.  Each pixel  is  in  of  the two
  866.        states --  on  or  off (set  or reset).  If a pixel is on,  it is
  867.        represented by a dot on screen or  on printer paper  or a logical
  868.        high state in memory.
  869.             
  870.             To address a pixel,  we can use x and  y coordinate numbers.
  871.        It  is usually  represented as (x,y).  the top right  corner of a
  872.        frame is defined as the origin of the physical  coordinate system
  873.        which  as  0  x  and  y  coordinate  value  (i.e.  (0,0)).  The x
  874.        coordinate of a pixel on the same horizontal line increase  as we
  875.        move right. The y coordinate of a pixel on the same vertical line
  876.        increase  as  we  move  downwards.  This  is  different  from the
  877.        coordinate system we usually used which has y coordinate increase
  878.        as we move upwards.
  879.             
  880.             The maximum value of the coordinate  numbers are  limited by
  881.        the size  of a  frame.  For example,  the number of pixels on IBM
  882.        color graphics adapter  are 640  (horizontal) and 200 (vertical).
  883.        Therefore legal x and y coordinate numbers are 0  to 639 and 0 to
  884.        199 respectively.
  885.             
  886.             Physical coordinate  numbers are only  used  in one external
  887.        interface function.  All  other functions use  logical coordinate
  888.        numbers which will be described in the next section.
  889.  
  890.        
  891.        4.2  Logical Coordinate System
  892.  
  893.             Logical coordinate system provides a convenient way  to look
  894.        at your frame.  Initially, the logical coordinate numbers are the
  895.        same as the physical coordinate  number.  The relationship can be
  896.        changed using SetOrg and RelOrg functions which will be described
  897.        later.
  898.             
  899.             The  relationship  between logical  and  physical coordinate
  900.        system can be  described in  several ways  and  different  way of
  901.        thinking helps in  different situation.  So  I will  describe all
  902.        three ways I can think of.
  903.  
  904.        
  905.        4.2.1  Setting Origin
  906.  
  907.             The logical coordinate  system  has  the  same  size  as the
  908.        physical coordinate  system.  Each pixel is one-one corresponding
  909.        between the two systems. The difference is that any pixels within
  910.        the logical coordinate system can  be defined as the  origin.
  911.             
  912.             Suppose your  frame size  is  640  by  200.  You  can define
  913.        (300,100)  in  physical  coordinate  system as the origin  in the
  914.        logical coordinate system.  The legal range of logical coordinate
  915.        numbers  will be  -320  to +319  and -100  to +99 for the x and y
  916.        coordinates respectively.  Any attempt to write outside the legal
  917.        space will be ignored.
  918.  
  919.                                      - 10 -
  920.  
  921.  
  922.  
  923.  
  924.  
  925.        GRAD User's Manual                                    June 7, 1987
  926.  
  927.             
  928.             
  929.             It is  legal to  define  a point  outside  the physical
  930.             coordinate system as the origin.  For  example, you can
  931.             define (-10,-10) as the origin. Legal coordinate number
  932.             for  x and y axes  will  be  10  to  649  and 10 to 209
  933.             respectively.
  934.             
  935.  
  936.        
  937.        4.2.2  Translation
  938.  
  939.             The logical and physical  coordinate  numbers are  offset by
  940.        fixed numbers specified by you.
  941.             
  942.             An  example of  this  situation  is  when  several identical
  943.        figures are required to draw on the frame.  Instead of  repeating
  944.        the  calling sequence  with different coordinate numbers,  we can
  945.        create a  subroutine  including  the  functions  for  drawing one
  946.        figure. We call the same subroutine as many times as required and
  947.        set different translation values in between two calls.
  948.  
  949.        
  950.        4.2.3  Windowing
  951.  
  952.             Try to imagine you are standing before a large square dinner
  953.        table. On the table, there is a piece of paper (normal size) with
  954.        its sides parallel to the edges of the table.  You are  holding a
  955.        special pen will only leave mark on the paper only but not on the
  956.        table.  You can draw anywhere  on the table.  However, only those
  957.        drawings passing the paper can be seen.
  958.             
  959.             This is an analogy of the relationship  between the physical
  960.        and  logical coordinate system.  The dinner table  is the logical
  961.        coordinate  system space,  the paper is  the  physical coordinate
  962.        system (or frame)  and the GRAD  functions are the  pen.  You can
  963.        place the frame anywhere within the logical coordinate space.
  964.             
  965.             The x and y coordinate  numbers  in  the  logical coordinate
  966.        space must be in the range of -32768 to +32767.
  967.  
  968.        
  969.        4.3  Related Functions
  970.  
  971.             There are two functions for the  control  of  the coordinate
  972.        system. They are:
  973.             
  974.             SetOrg(x,y) Set the point (x,y) in the physical coordinate
  975.                         system as the origin in the logical coordinate
  976.                         system.
  977.             
  978.             RelOrg(x,y) Set the point (x,y) in the logical coordinate 
  979.                         system as the new origin in the logical 
  980.                         coordinate system.
  981.  
  982.        
  983.  
  984.  
  985.  
  986.                                      - 11 -
  987.  
  988.  
  989.  
  990.  
  991.  
  992.        GRAD User's Manual                                    June 7, 1987
  993.  
  994.        4.3.1  SetOrg
  995.  
  996.                SetOrg(x,y);
  997.                int x,y;
  998.  
  999.        a. If you consider the logical coordinate system as  described in
  1000.           4.2.1,  to set (x,y) as the origin, the function call required
  1001.           is:
  1002.                SetOrg(x,y);
  1003.  
  1004.        b. If you consider the logical coordinate system  as described in
  1005.           4.2.2,  to set a and b pixels of  translation in x  and y axes
  1006.           will require the function call:
  1007.                SetOrg(a,b);
  1008.  
  1009.        c. If you consider the logical coordinate  system as described in
  1010.           4.2.3 and you want to place the upper left corner of the frame
  1011.           at (u,v) of the logical space, the function call required is:
  1012.                SetOrg(-u,-v);
  1013.  
  1014.        FUNCTIONS INCLUDED
  1015.  
  1016.                RelOrg, SetWin, ResetWin
  1017.  
  1018.        
  1019.        4.3.2  RelOrg
  1020.  
  1021.             The function of RelOrg is exactly the same  as SetOrg except
  1022.        the parameter specified is add to the existing setting instead of
  1023.        replacing the settings.
  1024.  
  1025.        
  1026.        4.4  Summary
  1027.  
  1028.             All coordinate  number  described in  this  manual except in
  1029.        this chapter  are  logical  coordinate  numbers  unless otherwise
  1030.        specified. Initially, the physical and logical coordinate numbers
  1031.        are the  same.  If you do not change it  by one  of the functions
  1032.        SetOrg and RelOrg, they are equivalent.
  1033.             
  1034.             The x coordinate number increase as it move to the right and
  1035.        the y  coordinate number increase  as it move  downwards. The top
  1036.        left corner  of  a frame is  the  origin  (0,0)  of  the physical
  1037.        coordinate system.
  1038.             
  1039.             
  1040.             
  1041.             
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.                                      - 12 -
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.        GRAD User's Manual                                    June 7, 1987
  1060.  
  1061.        5   Setting Window
  1062.  
  1063.             Windowing is one of the most important  features provided in
  1064.        GRAD.  Every function described  in this manual  which may change
  1065.        the  frame in  any way is  affected  by the  window setting. Only
  1066.        those  changes which are inside  the  window  are  permitted. Any
  1067.        attempt to change any pixels outside the window are ignored.
  1068.             
  1069.             The pixels outside the window  are essentially  frozen. They
  1070.        are unable to change the state until they are un-frozen.
  1071.             
  1072.             Therefore it is easy to create several windows in  the frame
  1073.        which  are  logically  separated  from  each  others. Furthermore
  1074.        additional  routines  are provided  to facilitate the  writing of
  1075.        application which need to maintain several window in the frame.
  1076.             
  1077.             A  simple  example of  creating and  maintaining windows are
  1078.        included later in this chapter.
  1079.             
  1080.             Only 2  functions in GRAD are directly related  to windowing
  1081.        (but most functions in GRAD are indirectly  related to  it). They
  1082.        are:
  1083.                
  1084.                ResetWin        Reset the window size to frame size
  1085.                SetWin          Set the window to the desired size
  1086.  
  1087.        
  1088.        5.1  Function Description
  1089.  
  1090.        5.1.1  ResetWin
  1091.  
  1092.                ResetWin()
  1093.  
  1094.        RETURN VALUE
  1095.             none
  1096.             
  1097.        DESCRIPTION
  1098.             
  1099.             Reset the window size to the current frame size.
  1100.             
  1101.        EXAMPLE
  1102.  
  1103.                ResetWin();
  1104.  
  1105.        FUNCTIONS INCLUDED
  1106.             SetWin, SetOrg, RelOrg
  1107.  
  1108.        
  1109.        5.1.2  SetWin
  1110.  
  1111.                SetWin(x1,y1,x2,y2);
  1112.                int x1,y2,x2,y2;
  1113.  
  1114.        RETURN VALUE
  1115.             none
  1116.             
  1117.        DESCRIPTION
  1118.             
  1119.  
  1120.                                      - 13 -
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.        GRAD User's Manual                                    June 7, 1987
  1127.  
  1128.             A window must be rectangular  in shape.  (x1,y1) and (x2,y2)
  1129.        are coordinates of the opposite corners of the  window. The order
  1130.        is not  important.  Both (x1,y1)  and (x2,y2) are included in the
  1131.        window.
  1132.             
  1133.             If (x1,y1)  and/or (x2,y2)  is/are  outside  the  frame, the
  1134.        window set will be the area of the window within the frame.
  1135.             
  1136.        EXAMPLE
  1137.  
  1138.                SetWin(100,100,200,200);
  1139.  
  1140.             The width and height of the window are both 101 pixels.
  1141.             
  1142.        FUNCTIONS INCLUDED
  1143.             ResetWin, RelOrg, SetOrg
  1144.  
  1145.        
  1146.        5.2  Example
  1147.  
  1148.        /* Below is code segment in C demostrating the use of window. */
  1149.        /* Some of the functions are not yet discussed. So you may    */
  1150.        /* wish to skip this section for the first reading.           */
  1151.  
  1152.        ResetWin();
  1153.        PlotType(1);
  1154.        HorzLine(-10000,-10000,20000,20000);  /* Clear Frame */
  1155.        PlotType(0);    /* select OR type */
  1156.        SetOrg(99,19);  
  1157.        Rectangle(0,0,203,103); /* A rectangle enclosing the window */
  1158.        RelOrg(1,1);    /* top-left-hand corner of the window */
  1159.        SetWin(0,0,200,100);    /* set window */
  1160.        window1=EnvSave(0);     /* save all the environment setting */
  1161.        SetOrg(400,20);         /* move to the second window */
  1162.        SetWin(0,0,100,100);    /* set window */
  1163.        HorzLine(0,0,1000,1000); /* Set all the pixels inside window */
  1164.        PlotType(1);            /* select AND type */
  1165.        window2=EnvSave(0);     /* save all the settings */
  1166.  
  1167.        Circle(50,50,80); /* setting is not affected, draws in window2 */
  1168.        Line(0,0,200,200); 
  1169.        Line(100,0,0,100);
  1170.  
  1171.        EnvRsto(window1,KEEP_SLOT); /* restore environment of window1 */
  1172.        WriteStr(0,LEFT,0,10,
  1173.              "The drawing in this frame is completely unaffected",0,0);
  1174.        WriteStr(0,LEFT,0,20,
  1175.              "By the drawing in the other frame.",0,0);
  1176.  
  1177.        EnvRsto(window2,KEEP_SLOT); /* back to window2 */
  1178.        SolidFill(40,50);
  1179.  
  1180.        EnvRsto(window1,KEEP_SLOT); /* back to window1 */
  1181.        WriteStr(0,LEFT,0,50,
  1182.              "You may switch back and forth between the 2 window",0,0);
  1183.  
  1184.        
  1185.  
  1186.  
  1187.                                      - 14 -
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.        GRAD User's Manual                                    June 7, 1987
  1194.  
  1195.        6   GRAD Environment
  1196.  
  1197.             Several parameters of GRAD has global effect.  For examples,
  1198.        plot type,  frame  number,  window setting,  ...et  cetera. These
  1199.        settings are called the environment of GRAD.
  1200.             
  1201.             Sometimes,  one  may wish  to  save  the current environment
  1202.        settings and restore it later. For instances when several windows
  1203.        are using at the same time.
  1204.             
  1205.             GRAD  provides  two  functions  to  save  and  restore these
  1206.        environment settings. You may selectively restore some or all the
  1207.        settings. Those two functions are:
  1208.  
  1209.                EnvSave         Save the current environment
  1210.                EnvRsto         Restore the environment saved
  1211.  
  1212.        
  1213.        6.1  Functions Description
  1214.  
  1215.        6.1.1  EnvSave
  1216.  
  1217.                EnvSave(slot_nu);
  1218.                int slot_nu;
  1219.  
  1220.        RETURN VALUE
  1221.             0  means no more slot  available.  All other positive number
  1222.        means environment is save in the that slot number.
  1223.  
  1224.        DESCRIPTION
  1225.  
  1226.             slot_nu can be from 0 to the maximum slot number. If slot_nu
  1227.        number is 0,  EnvSave will search for an  empty slot.  If none is
  1228.        found,  0 will be returned otherwise the slot number used will be
  1229.        returned.
  1230.             
  1231.             When a slot  number  is  given,  current environment will be
  1232.        saved in  that  slot  number  even  if  that  slot  is used. This
  1233.        provides  a  means  to  dedicate  a  certain  slot  number  for a
  1234.        particular application.  Contents can be changed without worrying
  1235.        about any change of slot number.
  1236.             
  1237.             The following settings  are save  by  EnvSave: frame number,
  1238.        window coordinates, origin, plot type, style and font number.
  1239.             
  1240.             EnvSave will not change any of the settings.
  1241.             
  1242.        Note : When you change active frame,  both the  origin and window
  1243.               setting are saved.  When  the frame  is  re-selected, they
  1244.               will be restored. See also SelectFrame
  1245.  
  1246.        EXAMPLES
  1247.                EnvSave(0);
  1248.  
  1249.             Save the current environment in the next unused slot.
  1250.  
  1251.        FUNCTIONS INCLUDED
  1252.             EnvRsto
  1253.  
  1254.                                      - 15 -
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.        GRAD User's Manual                                    June 7, 1987
  1261.  
  1262.        6.1.2  EnvRsto
  1263.  
  1264.                EnvRsto(slot_nu, options);
  1265.                int slot_nu, options;
  1266.  
  1267.        RETURN VALUE
  1268.             none
  1269.  
  1270.        DESCRIPTION
  1271.  
  1272.             EnvRsto will  restore all  or  partial  environment settings
  1273.        saved in the slot.  The slot number should be a value returned by
  1274.        EnvSave.  However,  slot number  0  has special meaning.  If 0 is
  1275.        given,  the environment settings at the time when  the program is
  1276.        first started are restored.
  1277.             
  1278.             The default options are to restore all  settings and release
  1279.        the  slot.  You  may change  the default by  using  the following
  1280.        options.  (The definition of the option can be found in  the file
  1281.        GRADENV.H)
  1282.          
  1283.          KEEP_SLOT     do not release the slot
  1284.          KEEP_WIN      keep the current window setting
  1285.          KEEP_ORG      keep the current origin
  1286.          KEEP_STYLE    keep the current plot style
  1287.          KEEP_PLOTTYPE keep the current plot type
  1288.          KEEP_FRAME    keep the current active frame
  1289.          KEEP_FONT     keep the current font
  1290.          
  1291.             To combine more than 1 options, use bitwise OR operator '|'.
  1292.  
  1293.        EXAMPLE
  1294.                EnvRsto(0);
  1295.  
  1296.             Restore all default settings.
  1297.             
  1298.        FUNCTIONS INCLUDED
  1299.             EnvSave
  1300.  
  1301.        
  1302.        7   Selection of Plot Type
  1303.  
  1304.             Each pixel in the frame must be in one of the two  states --
  1305.        either set or reset. When GRAD draws in the frame, it can force a
  1306.        pixel to set or reset or reverse the state.  In GRAD terminology,
  1307.        the three types of operations are  called OR,  AND and XOR. Their
  1308.        function codes are 0, 1 and 2 respectively.
  1309.             
  1310.           Code    Type         Description
  1311.            0       OR          Force a pixel to set state
  1312.            1       AND         Force a pixel to reset state
  1313.            2       XOR         Reverse the state of a pixel
  1314.           
  1315.           
  1316.             Every GRAD function which draws to the frame  is affected by
  1317.        the current plot type.  The default plot type is OR.  The name of
  1318.        the function to  change the plot type  is PlotType which  will be
  1319.        described in next section.
  1320.  
  1321.                                      - 16 -
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.        GRAD User's Manual                                    June 7, 1987
  1328.  
  1329.        7.1  Related Function
  1330.  
  1331.        7.1.1  PlotType
  1332.  
  1333.                ret=PlotType(type);
  1334.                int ret, type;
  1335.  
  1336.        RETURN VALUE
  1337.             The plot type (between 0 and 3) used before this function is
  1338.        executed.
  1339.             
  1340.        DESCRIPTION
  1341.             Set the plot type according to the table below:
  1342.             
  1343.           Code    Type         Description
  1344.            0       OR          Force a pixel to set state
  1345.            1       AND         Force a pixel to reset state
  1346.            2       XOR         Reverse the state of a pixel
  1347.            3       OR          same as type 0
  1348.             
  1349.             If the type specified is greater than  3,  then it will take
  1350.        module 4 of the value given and set according to the table above.
  1351.             
  1352.        EXAMPLE
  1353.  
  1354.                PlotType(0);
  1355.  
  1356.        FUNCTIONS INCLUDED
  1357.  
  1358.                none
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.                                      - 17 -
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.        GRAD User's Manual                                    June 7, 1987
  1395.  
  1396.        8   Dot Plotting and Line Drawing
  1397.  
  1398.             This chapter will describe the following functions:
  1399.             
  1400.             Dot(x,y)
  1401.                Plot a single dot
  1402.             
  1403.             SetStyle(style)
  1404.                Set the line style
  1405.             
  1406.             HorzLine(x,y,length,width)
  1407.                Draws  a  horizontal  line  starting  from  (x,y)  in the
  1408.                direction of increasing x.  The width of the  line extend
  1409.                in the direction of increasing y.
  1410.                
  1411.             VertLine(x,y,length,width)
  1412.                Draws  a  vertical  line  starting  from   (x,y)  in  the
  1413.                direction of increasing y.  The width of  the line extend
  1414.                in the direction of increasing x.
  1415.  
  1416.        
  1417.        8.1  Functions Description
  1418.  
  1419.        8.1.1  Dot
  1420.  
  1421.                Dot(x,y);
  1422.                int x,y;
  1423.  
  1424.        RETURN VALUE
  1425.             none
  1426.  
  1427.        DESCRIPTION
  1428.             It plot a dot at location (x,y) of current active frame.
  1429.  
  1430.        EXAMPLE
  1431.  
  1432.                Dot(10,10)
  1433.  
  1434.        FUNCTIONS INCLUDED
  1435.  
  1436.             HorzLine, VertLine
  1437.  
  1438.        
  1439.        8.1.2  SetStyle
  1440.  
  1441.                old=SetStyle(style);
  1442.                unsigned int style, old;
  1443.  
  1444.        RETURN VALUE
  1445.             return the old style setting
  1446.             
  1447.        DESCRIPTION
  1448.             
  1449.             It sets the style of the line  drawn by  HorzLine, VertLine,
  1450.        Line,  Arc1,  Arc2,  Earc1  and Earc2.  Style is  a 16-bit value.
  1451.        Default is  0xffff.  That means the lines drawn  are  solid line.
  1452.        When you call SetStyle,  it just move the value  of the parameter
  1453.  
  1454.  
  1455.                                      - 18 -
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.        GRAD User's Manual                                    June 7, 1987
  1462.  
  1463.        to a internal variable except when the value is 0.  In that case,
  1464.        the  original  value will  be  inverted.  (i.e. exclusive or with
  1465.        0xffff).
  1466.             
  1467.        EXAMPLES
  1468.                oldstyle=SetStyle(0xffff);      /* save original style */
  1469.                HorzLine(0,0,100,1);
  1470.                SetStyle(0x3333);
  1471.                HorzLine(0,10,100,1);
  1472.                SetStyle(0);
  1473.                HorzLine(0,20,100,1);
  1474.                SetStyle(0x11ff);
  1475.                HorzLine(0,30,100,1);
  1476.                SetStyle(oldstyle);     /* restore original style */
  1477.             
  1478.             
  1479.             The first line is a solid line. The second and third example
  1480.        draw 2  dotted lines with 2 dots in every 4 dot position. However
  1481.        the ink dots position are complementary of each other. The fourth
  1482.        example draw a mixed of dotted and dashed line.
  1483.             
  1484.        FUNCTIONS INCLUDED
  1485.  
  1486.                none
  1487.  
  1488.        
  1489.        8.1.3  HorzLine
  1490.  
  1491.                HorzLine(x,y,length,width);
  1492.                int x,y,length,width;
  1493.  
  1494.        RETURN VALUE
  1495.             none
  1496.  
  1497.        DESCRIPTION
  1498.             It  draws  a  horizontal  line  (i.e.  parallel  to  x axis)
  1499.        starting from  the point (x,y)  in the increasing  direction of x
  1500.        coordinate. If the length or width is less than or equal to zero,
  1501.        nothing will be drawn.  The width of the line will extend  in the
  1502.        increasing direction of y coordinate.  The line drawn is affected
  1503.        by the style set by SetStyle.
  1504.             
  1505.        EXAMPLE
  1506.                HorzLine(100,100,100,2);
  1507.             
  1508.             Draws a line of length 100 pixels and width is 2. That means
  1509.        a total of 200 pixels are drawn.
  1510.             
  1511.        FUNCTIONS INCLUDED
  1512.                Dot, VertLine
  1513.  
  1514.        
  1515.        8.1.4  VertLine
  1516.  
  1517.                VertLine(x,y,length,width);
  1518.                int x,y,length,width;
  1519.  
  1520.        RETURN VALUE
  1521.  
  1522.                                      - 19 -
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.        GRAD User's Manual                                    June 7, 1987
  1529.  
  1530.             none
  1531.  
  1532.        DESCRIPTION
  1533.             It draws a vertical line (i.e.  parallel to y axis) starting
  1534.        from the point (x,y) in the increasing direction of y coordinate.
  1535.        If the length  or  width is less than  or equal  to zero, nothing
  1536.        will be drawn.  The width of the line  extends in  the increasing
  1537.        direction  of  x coordinate.  The  line drawn is affected  by the
  1538.        STYLE set by SetStyle.
  1539.             
  1540.        EXAMPLE
  1541.                VertLine(100,100,100,2);
  1542.             
  1543.             Draws a line of length 100 pixels and width is 2. That means
  1544.        a total of 200 pixels are drawn.
  1545.             
  1546.        FUNCTIONS INCLUDED
  1547.                Dot, HorzLine
  1548.  
  1549.        
  1550.  
  1551.        8.2  Efficiency Consideration
  1552.  
  1553.             HorzLine and VertLine never call Dot to draw  line. They use
  1554.        a much faster method to draw line.  Therefore,  it is much longer
  1555.        to plot 100 consecutive dots than draw a 100 pixels long vertical
  1556.        or horizontal line.
  1557.             
  1558.             HorzLine  in general  draws faster than VertLine  in drawing
  1559.        lines with same length and width. Therefore if you want to draw a
  1560.        block with length and width approximately the same,  it is better
  1561.        to use HorzLine. However, if the style setting is not 0xffff, the
  1562.        result by HorzLine and VertLine are different.
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.                                      - 20 -  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.        GRAD User's Manual                                    June 7, 1987
  1596.  
  1597.        9   Circle, Ellipse and Arc
  1598.  
  1599.             GRAD library provides extensive support for drawing circles,
  1600.        ellipses and arcs.
  1601.             
  1602.             The  circle command  in some programs  or libraries actually
  1603.        draws a polygon.  That  may look  like a circle when  the desired
  1604.        circle is small. But when the desired circle is large, the output
  1605.        will not be a circle any more.
  1606.             
  1607.             The circle and ellipse function in GRAD draw  `true' circles
  1608.        and ellipses. What it means is then the circles and ellipses when
  1609.        displayed  or  printed on  a media with  aspect ratio  equal to 1
  1610.        (i.e.  the width and height of a pixel is  equal),  each pixel of
  1611.        the  circles or  ellipses  is  less  than or equal to  half pixel
  1612.        distance from  a real  circle  or  ellipse  with  the  same size.
  1613.        Furthermore,  each pixel will be adjacent to 2  and only 2 pixels
  1614.        of the circle  or ellipse.  So the region enclosed can  be filled
  1615.        using the fill command.
  1616.             
  1617.             The functions that will be described in this chapter are:
  1618.                Circle          Draws a logical circle
  1619.                Ellipse         Draws a logical ellipse
  1620.                FillCircle      Draws a disc
  1621.                FillEllipse     Draws a elliptical disc
  1622.                Arc1            Arc drawing 1
  1623.                Earc1           Elliptical arc drawing 1
  1624.                Arc2            Arc drawing 2
  1625.                Earc2           Elliptical arc drawing 2
  1626.                ArcPoint        Gives the coordinates of 2 end points
  1627.                                of Arc2 or Earc2
  1628.                
  1629.             Since the aspect ratio of  the output  device may  not be 1.
  1630.        The circle drawn by Circle may not look like a  circle on output.
  1631.        If  you want to get `circle'  in  the output,  you should draw an
  1632.        ellipse with  appropriate  ratio of horizontal  and vertical axes
  1633.        specified.  For example,  the width of  a pixel is  twice  of the
  1634.        height of the pixel on a certain output device. In order to get a
  1635.        `circle', the length of the horizontal axis should be half of the
  1636.        vertical axis.
  1637.  
  1638.        
  1639.        9.1  Functions Description
  1640.  
  1641.        9.1.1  Circle
  1642.  
  1643.                Circle(center_x, center_y, radius);
  1644.                int center_x, center_y, radius;
  1645.  
  1646.        RETURN VALUE
  1647.             none
  1648.  
  1649.        DESCRIPTION
  1650.  
  1651.             This function will draw a logical circle.  radius is in term
  1652.        of pixels and must be greater than or equal to 0. The circle draw
  1653.        is  not affected  by the plot style setting.  (See  also Arc1 and
  1654.        Arc2)
  1655.  
  1656.                                      - 21 -
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.        GRAD User's Manual                                    June 7, 1987
  1663.  
  1664.             
  1665.        EXAMPLE
  1666.  
  1667.                Circle(100,100,20);
  1668.  
  1669.             Assume the window is larger than  the circle.  Then the left
  1670.        most,  right most,  top and bottom points  of the  circle will be
  1671.        (80,100), (120,100), (100,80) and (100,120) respectively.
  1672.  
  1673.        FUNCTIONS INCLUDED
  1674.             Arc1
  1675.  
  1676.        
  1677.        9.1.2  Ellipse
  1678.  
  1679.                Ellipse(center_x, center_y, horiz_axis, vert_axis);
  1680.                int center_x, center_y, horiz_axis, vert_axis;
  1681.  
  1682.        RETURN VALUE
  1683.             none
  1684.  
  1685.        DESCRIPTION
  1686.  
  1687.             This  function  will  draw  an  ellipse.  horiz_axis  is the
  1688.        distance in pixel from the center to the left most or  right most
  1689.        point of the ellipse.  vert_axis is the distance from  the center
  1690.        to the top or  bottom  point of  the ellipse.  If  horiz_axis and
  1691.        vert_axis is equal,  the result will be the same as  using Circle
  1692.        will radius  set to  either horiz_axis or  vert_axis. The ellipse
  1693.        drawn  is  not affected  by the  plot style.  (See also Earc1 and
  1694.        Earc2)
  1695.             
  1696.        EXAMPLE
  1697.  
  1698.                Ellipse(100,100,40,20);
  1699.  
  1700.        FUNCTIONS INCLUDED
  1701.             Earc1
  1702.  
  1703.        
  1704.  
  1705.        9.1.3  FillCircle
  1706.  
  1707.                FillCircle(center_x, center_y, radius);
  1708.                int center_x, center_y, radius;
  1709.  
  1710.        RETURN VALUE
  1711.             none
  1712.  
  1713.        DESCRIPTION
  1714.  
  1715.             This function is same as Circle except that the circle drawn
  1716.        will be filled.
  1717.             
  1718.        EXAMPLE
  1719.  
  1720.                FillCircle(100,100,20);
  1721.  
  1722.  
  1723.                                      - 22 -
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.        GRAD User's Manual                                    June 7, 1987
  1730.  
  1731.             Assume the window is larger than  the circle.  Then the left
  1732.        most,  right most,  top and bottom points  of the  circle will be
  1733.        (80,100), (120,100), (100,80) and (100,120) respectively.
  1734.  
  1735.        FUNCTIONS INCLUDED
  1736.             FillEllipse, HorzLine, VertLine
  1737.  
  1738.        
  1739.        9.1.4  FillEllipse
  1740.  
  1741.                FillEllipse(center_x, center_y, horiz_axis, vert_axis);
  1742.                int center_x, center_y, horiz_axis, vert_axis;
  1743.  
  1744.        RETURN VALUE
  1745.             none
  1746.  
  1747.        DESCRIPTION
  1748.  
  1749.             This function is same as Ellipse except that the output will
  1750.        be an filled ellipse.
  1751.             
  1752.        EXAMPLE
  1753.  
  1754.                FillEllipse(100,100,40,20);
  1755.  
  1756.        FUNCTIONS INCLUDED
  1757.                FillCircle, HorzLine, VertLine
  1758.  
  1759.        
  1760.  
  1761.        9.1.5  Arc1
  1762.  
  1763.                Arc1(center_x, center_y, radius, arc_spec);
  1764.                int center_x, center_y, radius, arc_spec;
  1765.  
  1766.        RETURN VALUE
  1767.             none
  1768.  
  1769.        DESCRIPTION
  1770.  
  1771.             In the function Arc1, a circle is divided into 8 equal parts
  1772.        as defined later.  You may select any part or parts of the circle
  1773.        to  draw. Moreover, the arcs drawn are affected by the line style
  1774.        selected. 
  1775.             
  1776.             8   equal  parts  of  the  circle  is  obtained  by  drawing
  1777.        horizontal,  vertical and 2  diagonal lines (slope  is  1 and -1)
  1778.        through the center of the circle.  You specify which part  of the
  1779.        circle is required in the parameter arc_spec.
  1780.             
  1781.             The name  of  the eight parts  are  defined  as  follows (in
  1782.        clockwise direction):
  1783.          
  1784.          UP_RIGHT, RIGHT_UP, RIGHT_DOWN, DOWN_RIGHT, DOWN_LEFT,
  1785.          LEFT_DOWN, LEFT_UP and UP_LEFT.
  1786.  
  1787.        Additional constants defined include:
  1788.          UPPER_HALF    = RIGHT_UP | UP_RIGHT | UP_LEFT | LEFT_UP
  1789.  
  1790.                                      - 23 -
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.        GRAD User's Manual                                    June 7, 1987
  1797.  
  1798.          LOWER_HALF    = LEFT_DOWN | DOWN_LEFT | DOWN_RIGHT | RIGHT_DOWN
  1799.          LEFT_HALF     = UP_LEFT | LEFT_UP | LEFT_DOWN | DOWN_LEFT
  1800.          RIGHT_HALF    = DOWN_RIGHT | RIGHT_DOWN | RIGHT_UP | UP_RIGHT
  1801.          
  1802.             These constants can be found in the header file GRADARC.H
  1803.             
  1804.             As mentioned above,  the arc drawn is  affected  by the plot
  1805.        style selected.  Due to the way a circle  is drawn,  the style of
  1806.        the arc may not be  uniform.  The result  would be  better if the
  1807.        style setting is symmetrical.  (i.e. the bits when read from left
  1808.        to right or right to left are the same)
  1809.  
  1810.        EXAMPLES
  1811.        (1)     Arc1(50,50,30,UPPER_HALF);
  1812.        (2)     SetStyle(0xc3c3);
  1813.                Arc1(100,100,30,UPPER_HALF | LOWER_HALF);
  1814.  
  1815.             First example will draw the upper half  of  the circle only.
  1816.        The   second  example  will   draw  the  whole  circle   but  the
  1817.        circumference is drawn in dotted line style.
  1818.  
  1819.        FUNCTIONS INCLUDED
  1820.             Circle
  1821.  
  1822.        
  1823.        9.1.6  Earc1
  1824.  
  1825.                Earc1(center_x, center_y, horiz_axis, vert_axis,
  1826.                        arc_spec);
  1827.                int center_x, center_y, horiz_axis, vert_axis, arc_spec;
  1828.  
  1829.        RETURN VALUE
  1830.             none
  1831.  
  1832.        DESCRIPTION
  1833.             Earc1  is  very   similar to Arc1.  Earc1  draws a arc of an
  1834.        ellipse instead of  a arc  of  a  circle.  The  ellipse  is still
  1835.        divided into 8 region. The four lines to divide the ellipse are a
  1836.        horizontal line, a vertical line and two lines joining the points
  1837.        which slope of  the tangent is  1  and -1 respectively. Each line
  1838.        must  go  through the center.  If you do  not understand  how the
  1839.        ellipse is divided, just try some experiments.
  1840.             
  1841.             The naming of each  part is exactly the same  as  Arc1. They
  1842.        are:
  1843.          UP_RIGHT, RIGHT_UP, RIGHT_DOWN, DOWN_RIGHT, DOWN_LEFT,
  1844.          LEFT_DOWN, LEFT_UP and UP_LEFT.
  1845.  
  1846.        Additional constants defined include:
  1847.          UPPER_HALF    = RIGHT_UP | UP_RIGHT | UP_LEFT | LEFT_UP
  1848.          LOWER_HALF    = LEFT_DOWN | DOWN_LEFT | DOWN_RIGHT | RIGHT_DOWN
  1849.          LEFT_HALF     = UP_LEFT | LEFT_UP | LEFT_DOWN | DOWN_LEFT
  1850.          RIGHT_HALF    = DOWN_RIGHT | RIGHT_DOWN | RIGHT_UP | UP_RIGHT
  1851.          
  1852.             These constants can be found in the header file GRADARC.H
  1853.             
  1854.  
  1855.  
  1856.  
  1857.                                      - 24 -
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.        GRAD User's Manual                                    June 7, 1987
  1864.  
  1865.             The arcs drawn are affected by the plot style  selected. Due
  1866.        to the way an ellipse is drawn,  the style of the arc  may not be
  1867.        uniform.  The  result  would be  better  if the  style setting is
  1868.        symmetrical. (i.e. the bits when read from left to right or right
  1869.        to left are the same)
  1870.  
  1871.        EXAMPLES
  1872.        (1)     Earc1(50,50,30,60,UPPER_HALF);
  1873.        (2)     SetStyle(0xc3c3);
  1874.                Earc1(100,100,30,60,UPPER_HALF | LOWER_HALF);
  1875.  
  1876.             First example will draw the upper half of  the ellipse only.
  1877.        The  second  example  will   draw  the  whole  ellipse   but  the
  1878.        circumference is drawn in dotted line style.
  1879.             
  1880.        FUNCTIONS INCLUDED
  1881.             Ellipse
  1882.  
  1883.        
  1884.  
  1885.        9.1.7  Arc2
  1886.  
  1887.                Arc2(center_x, center_y, radius,
  1888.                         start_degree, degrees);
  1889.                int center_x, center_y, radius, start_degree, degrees;
  1890.  
  1891.        RETURN VALUE
  1892.             none
  1893.             
  1894.        DESCRIPTION
  1895.  
  1896.             This function draws a circular arc.  The angle of the arc is
  1897.        specified  in  terms of  degrees.  In order words,  the circle is
  1898.        divided  into 360  equal divisions.  You specify the starting and
  1899.        ending division to be drawn.
  1900.             
  1901.             The parameter  start_degree  can  be  any  value  within the
  1902.        allowable range of an integer.  Arc2 will take the positive value
  1903.        of start_degree mod 360 ( start_degree % 360 ).
  1904.             
  1905.             The parameter degrees can be  any values too.  However if it
  1906.        is larger than 360, it is set to 360. If it is less than or equal
  1907.        to zero, nothing will be drawn.
  1908.             
  1909.             The vertically  upward  direction is  considered  to  be the
  1910.        reference line. start_degree is the angle of the line joining the
  1911.        starting point of  the arc  and  center  and  the  reference line
  1912.        measured in clockwise direction. degrees is the angle between the
  1913.        lines joining the starting and ending points to the center.
  1914.             
  1915.             Immediately  after  execution  of  Arc2,  you  can  get  the
  1916.        coordinates  of  the starting  and  ending  points  by  using the
  1917.        function ArcPoint. See the description later in this chapter.
  1918.             
  1919.        EXAMPLES
  1920.        (1)     Arc2(100,100,50,270,180);
  1921.        (2)     Arc2(200,100,50,90,180);
  1922.  
  1923.  
  1924.                                      - 25 -
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.        GRAD User's Manual                                    June 7, 1987
  1931.  
  1932.             Example 1  draws the upper half of a circle. Example 2 draws
  1933.        the lower half of a circle.
  1934.             
  1935.        FUNCTIONS INCLUDED
  1936.             Arc1, Circle
  1937.  
  1938.        
  1939.  
  1940.        9.1.8  Earc2
  1941.  
  1942.                Earc2(center_x, center_y, horiz_axis, vert_axis,
  1943.                        start_degree, degrees);
  1944.                int center_x, center_y, horiz_axis, vert_axis;
  1945.                int start_degree, degrees;
  1946.  
  1947.        RETURN VALUE
  1948.             none
  1949.  
  1950.        DESCRIPTION
  1951.             Earc2  is  very  similar to  Arc2.  It draws elliptical arcs
  1952.        instead of  circular  arc.  The angle of the arc  is specified in
  1953.        terms of degrees. In order words, the ellipse is divided into 360
  1954.        divisions.  (note I do not  say equal division.)  You specify the
  1955.        starting and ending division to be drawn.
  1956.             
  1957.             The parameter  start_degree  can  be  any  value  within the
  1958.        allowable range of an integer.  Arc2 will take the positive value
  1959.        of start_degree mod 360 ( start_degree % 360 ).
  1960.             
  1961.             The parameter degrees can be  any values too.  However if it
  1962.        is larger than 360, it is set to 360. If it is less than or equal
  1963.        to zero, nothing will be drawn.
  1964.             
  1965.             The  vertically  upward  direction is  considered  to be the
  1966.        reference line.  Due to the limitation of the algorithm used, all
  1967.        angles are measured on a  output device with  aspect ratio (width
  1968.        of a pixel : height of a pixel) equal to vert_axis/horiz_axis. In
  1969.        other words, the ellipse appear as a `circle'.
  1970.             
  1971.             start_degree is the angle of  the line  joining the starting
  1972.        point of the arc and center  and the reference  line  measured in
  1973.        clockwise  direction.  degrees is  the  angle  between  the lines
  1974.        joining the starting and ending points to the center.
  1975.             
  1976.             Immediately  after  execution  of  Earc2,  you  can  get the
  1977.        coordinates  of  the starting  and  ending  points  by  using the
  1978.        function ArcPoint. See the description later in this chapter.
  1979.             
  1980.        EXAMPLES
  1981.        (1)     Earc2(100,100,60,30,270,180);
  1982.        (2)     Earc2(200,200,60,30,90,180);
  1983.  
  1984.             First  example draws the upper half  of  an  ellipse. Second
  1985.        example draws the lower half of an ellipse.
  1986.             
  1987.        FUNCTIONS INCLUDED
  1988.             Ellipse, Earc1
  1989.  
  1990.  
  1991.                                      - 26 -
  1992.  
  1993.  
  1994.  
  1995.  
  1996.  
  1997.        GRAD User's Manual                                    June 7, 1987
  1998.  
  1999.        9.1.9  ArcPoint
  2000.  
  2001.                ArcPoint(start_x, start_y, end_x, end_y);
  2002.                int *start_x, *start_y, *end_x, *end_y;
  2003.  
  2004.        RETURN VALUE
  2005.             none
  2006.             
  2007.        DESCRIPTION
  2008.             Using this function is only meaningful immediately after the
  2009.        execution of Arc2  or Earc2. If these are any other GRAD function
  2010.        calls in between, the values return may be incorrect.
  2011.             
  2012.             The return values are  stored in the four  parameters given.
  2013.        They  are the (logical)  coordinates  of the  starting and ending
  2014.        points  of  the arc just  drawn  without  considering  the window
  2015.        setting. That means if part of the arc is outside the window, the
  2016.        values  returned  is exactly the  same when the window  is larger
  2017.        than the arc.
  2018.             
  2019.        EXAMPLE
  2020.                Arc1(100,100,50,10,30);
  2021.                ArcPoint(&sx, &sy, &ex, &ey);
  2022.                Line(sx, sy, 100, 100); /* join the starting and ending
  2023.                Line(ex, ey, 100, 100);    point to the center         */
  2024.  
  2025.             A sector is drawn.
  2026.  
  2027.        FUNCTIONS INCLUDED
  2028.             none
  2029.  
  2030.        
  2031.        9.2  Hints
  2032.  
  2033.             Circle,  Arc1  and Arc2  are special cases of Ellipse, Earc1
  2034.        and Earc2.  They are provided because drawing circles are several
  2035.        times faster than drawing ellipse. If in one of your program, you
  2036.        use ellipse  most of the time  and only  requires drawing circles
  2037.        several times,  then you may use ellipse to  draw circles instead
  2038.        in order to reduce program size.
  2039.             
  2040.             Similarly,  Arc1  and Earc1  work faster than Arc2 and Earc2
  2041.        respectively. Use Arc1 and Earc1 whenever possible.
  2042.             
  2043.             ArcPoint is used with Arc2 and Earc2 only. It cannot be used
  2044.        with Arc1 and Earc1.
  2045.             
  2046.             Besides using Arc1,  Arc2, Earc1 and Earc2 to draw arcs, you
  2047.        can also use Circle and Ellipse to draw arcs. The technique is to
  2048.        define a window less than the complete circle or ellipse. So only
  2049.        part of the circle or ellipse is visible. This is useful when you
  2050.        do not need to draw an arc of exactly how many degrees. 
  2051.             
  2052.             Sometimes,  you may want  to draw a circle  or  a sector and
  2053.        then divided that into several smaller sector.  You may draw each
  2054.        small sectors individually but a better techniques is to draw the
  2055.        largest sector after combining the small ones then draw  lines to
  2056.        divided that.  In order to find the points on  the circumference,
  2057.  
  2058.                                      - 27 -
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.        GRAD User's Manual                                    June 7, 1987
  2065.  
  2066.        you  should first  define the window equal to  the center  of the
  2067.        circle (or ellipse).  Since  the window  only  include the center
  2068.        point,  the arc is not actually drawn  but the end points  of the
  2069.        arc are stilled calculated. See the example in GRADEGS.GCM.
  2070.             
  2071.             When you want to  know the end  points of a arc  but without
  2072.        actually drawing it out,  you must not define  the window outside
  2073.        the circle because Circle is clever enough not to draw it  but it
  2074.        is not clever to skip the drawing if the window  is  equal to the
  2075.        center point.
  2076.  
  2077.  
  2078.  
  2079.  
  2080.  
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.  
  2093.  
  2094.  
  2095.  
  2096.  
  2097.  
  2098.  
  2099.  
  2100.  
  2101.  
  2102.  
  2103.  
  2104.  
  2105.  
  2106.  
  2107.  
  2108.  
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.  
  2123.  
  2124.  
  2125.                                      - 28 -
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.        GRAD User's Manual                                    June 7, 1987
  2132.  
  2133.        10  4-connected Region Filling
  2134.  
  2135.             Region  filling  functions  are  very  useful  and powerful.
  2136.        However, you must be very careful when using them because if your
  2137.        area you wished  to  fill is not enclosed  by  a proper boundary,
  2138.        then the `paint' will leaks out may make your frame very `dirty'.
  2139.             
  2140.             The region filling functions in GRAD will fill a 4-connected
  2141.        region. The definition of a 4-connected region is:
  2142.             
  2143.             All pixels in a 4-connected region  can be  reached one from
  2144.             the other by a sequence of any of the four  one-pixel moves:
  2145.             up,   down,  left,  right,  without  crossing  any  boundary
  2146.             pixel(s).
  2147.             
  2148.        A boundary pixel is defined by its state (either  set  or reset).
  2149.        The state for boundary pixels depends  on the plot type  using at
  2150.        that  time.   It  will  be  explained  later  in   the  functions
  2151.        description.
  2152.  
  2153.             To  fill  a  4-connected  region,   you  need  to  give  the
  2154.        coordinates of  any one  point  in  the  region,  regions filling
  2155.        functions will look for every pixels in the region by themselves.
  2156.        Using any point in  the region  as the starting point  would give
  2157.        the same  result.  (Remark:  but the speed of filling may  have a
  2158.        slight  difference.  Furthermore,  in  current  implementation of
  2159.        PatternFill,  this statement is not completely  true.  It will be
  2160.        explained later when the function is described.)
  2161.             
  2162.             All pixels  outside the window  defined are consider  in the
  2163.        state  same  as the boundary pixels.  In other words,  no `paint'
  2164.        will be painted outside the window.  That means when you may fill
  2165.        a completely  blank frame to a pattern you  want  because maximum
  2166.        window size is the frame size.
  2167.             
  2168.             I try  to give a precise description of  what  the functions
  2169.        will do and will not do in  different situation.  However most of
  2170.        them are common sense.  If you have any problem  in understanding
  2171.        what I said above, try to do some experiments and them come back.
  2172.             
  2173.             The functions that will be described in this chapter are:
  2174.                SolidFill       Set all pixels in the region to the
  2175.                                same state.
  2176.                PatternFill     Fill the region with a user specified
  2177.                                pattern.
  2178.  
  2179.        
  2180.        10.1  Functions Description
  2181.  
  2182.        10.1.1  SolidFill
  2183.  
  2184.                SolidFill(x,y);
  2185.                int x,y;
  2186.  
  2187.        RETURN VALUE
  2188.             none
  2189.             
  2190.        DESCRIPTION
  2191.  
  2192.                                      - 29 -
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.        GRAD User's Manual                                    June 7, 1987
  2199.  
  2200.             SolidFill  will  set all pixels  in  the  4-connected region
  2201.        containing (x,y) to the same state. The state depends on the plot
  2202.        type selected at that time.  The boundary pixel state is the same
  2203.        as the state used for filling.  If plot type is 0  (OR type), the
  2204.        region will be set to set state.  If  plot type is  1 (AND type),
  2205.        the region  will be set to  reset state.  If plot type  is 2 (XOR
  2206.        type),  the state used  will depend on  the initial state  of the
  2207.        starting point (x,y).  If it is reset, the region will set to set
  2208.        state, otherwise the region will set to reset state.
  2209.             
  2210.             SolidFill requires  temporary  storage  from  the  stack for
  2211.        working  memory.  The  amount  of memory required  depends on the
  2212.        complexity of  the region.  If you see  the  message  saying that
  2213.        insufficient working memory for filling,  you should increase the
  2214.        stack  size  and try again.  (Look at  your  C compiler reference
  2215.        manual to  see how to  increase  the  stack  size.)  You  are not
  2216.        required to  purposely increase  the stack size  whenever you use
  2217.        fill functions because working storage of 40 bytes are sufficient
  2218.        for most situation.  (Default stack size in most C compiler is at
  2219.        least 2K bytes.)
  2220.             
  2221.        EXAMPLES
  2222.        (1)     PlotType(0);
  2223.                Arc2(100,100,45,150);
  2224.                ArcPoint(&x1, &y1, &x2, &y2);
  2225.                Line(x1,y1,100,100);
  2226.                Line(x2,y2,100,100);
  2227.                SolidFill(100,100);
  2228.        (2)     /* Assume the frame is completely blank at this time */
  2229.                PlotType(2);
  2230.                Circle(100,100,50);
  2231.                SolidFill(100,100);
  2232.                SolidFill(100,100);
  2233.  
  2234.             In the first example,  a sector of 150  degree is filled. In
  2235.        the second  example,  you will  see the  circle  filled  and then
  2236.        erased. Read the description above for explanation.
  2237.             
  2238.        FUNCTIONS INCLUDE
  2239.             PatternFill
  2240.  
  2241.        
  2242.        10.1.2  PatternFill
  2243.  
  2244.                PatternFill(x,y,patptr,0);
  2245.                int x,y,*patptr;
  2246.  
  2247.        RETURN VALUE
  2248.             none
  2249.             
  2250.        DESCRIPTION
  2251.             PatternFill is  very  similar to  SolidFill  except  that it
  2252.        fills  the region  in  user  specified  pattern  and  it  has one
  2253.        limitation in current implementation.
  2254.             
  2255.  
  2256.  
  2257.  
  2258.  
  2259.                                      - 30 -
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.        GRAD User's Manual                                    June 7, 1987
  2266.  
  2267.             patptr is a pointer pointing to a integer array of  size 16.
  2268.        The lower order 8 bit will be displayed on the left of the higher
  2269.        order 8  bit.  So you have to swap the lower and  higher  byte in
  2270.        defining your  pattern.  There  is  no  restriction  on  what the
  2271.        pattern should look like. It can be completely set or reset.
  2272.             
  2273.             Owing to some  implementation problems,  the current version
  2274.        of  PatternFill can only  guarantee  filling  of  simple regions.
  2275.        Simple region means the region within the outer boundary does not
  2276.        contain  any  pixel(s)   in  the  same  state  as  the  boundary.
  2277.        Otherwise,  part of the region may not be filled.
  2278.             
  2279.             The actual operation of PatternFill is like  this: The front
  2280.        line  of filling  after the first line  is drawn  will not change
  2281.        direction.  It will continue goes up or down.  Therefore, in some
  2282.        cases,  it can fill area other than simple region. For example, a
  2283.        small rectangle inside a much larger  one and the  starting point
  2284.        is  either  above or below  the small rectangle inside  the large
  2285.        rectangle,  then the whole region will be filled. If the starting
  2286.        point is at the right of the  small rectangle,  the region on the
  2287.        left of the small rectangle will not be filled.
  2288.             
  2289.             Although PatternFill is  not  a  complete  implementation of
  2290.        4-connected region  filling function,  it is  sufficient for most
  2291.        application such as filling pie charts, bar charts etc.
  2292.             
  2293.             The fourth parameter is  not used  in current implementation
  2294.        but it  must be set to  0  in order to be compatible  with future
  2295.        version of PatternFill.
  2296.  
  2297.        EXAMPLE
  2298.                static int pattern[16]={
  2299.                    0x1111, 0x2222, 0x4444, 0x8888,
  2300.                    0x1111, 0x2222, 0x4444, 0x8888,
  2301.                    0x1111, 0x2222, 0x4444, 0x8888,
  2302.                    0x1111, 0x2222, 0x4444, 0x8888 };
  2303.                PlotType(0);
  2304.                Box(100,100,10,50,2,2);
  2305.                PatternFill(105,105,pattern,0);
  2306.  
  2307.             The Box drawn in  the example  will  be  filled  with shaded
  2308.        lines.
  2309.             
  2310.        FUNCTIONS INCLUDED
  2311.             SolidFill
  2312.             
  2313.  
  2314.        
  2315.        10.2  Hints
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.                                      - 31 -
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.        GRAD User's Manual                                    June 7, 1987
  2333.  
  2334.        11  Text Characters Related Functions
  2335.  
  2336.             A character in GRAD can be completely blank or a block up to
  2337.        about   120   by  120   pixels(can   be   change   easily  during
  2338.        re-comilation).   Font  files  are  loaded  into   memory  during
  2339.        execution time so that you can access  to different  type of font
  2340.        easily.
  2341.             
  2342.             Currently, two types of font files are supported. First type
  2343.        is fixed size font.  Every character in the file  occupy the same
  2344.        space. The second type is variable size font. Some people call it
  2345.        proportional  spacing characters.  The  type of the font  file is
  2346.        transparent to the user except  in some situation when  the exact
  2347.        size and position of  a character or  a string  of characters are
  2348.        important,  then you may need to know whether it is fixed size or
  2349.        variable size. More on this later in this chapter.
  2350.             
  2351.             The functions that will be described in this chapter are:
  2352.                LoadFont    Load a font file into memory.
  2353.                SelectFont  Select the active font type.
  2354.                RemvFont    Remove the font from memory.
  2355.                WriteStr    Write a string of character using the current
  2356.                            font selected.
  2357.                ReadStr     Read a string from keyboard
  2358.                NextXY      get the next coordinates for WriteStr or
  2359.                            ReadStr
  2360.  
  2361.        
  2362.        11.1  Functions Description
  2363.  
  2364.        11.1.1  LoadFont
  2365.  
  2366.                font_number=LoadFont(fontfilename);
  2367.                int font_number;
  2368.                char *fontfilename;
  2369.  
  2370.        RETURN VALUE
  2371.             A font number
  2372.  
  2373.        DESCRIPTION
  2374.             fontfilename is a DOS file name.  When LoadFont is executed,
  2375.        the  whole font file will  be loaded into  memory.  It is kept in
  2376.        memory until it  is  removed by  the  function  call  RemvFont or
  2377.        termination  of  GRAD.  When error occurs,  font number 0 will be
  2378.        returned.  You may  test  for  zero  to  perform  your  own error
  2379.        processing. See also SelectFont.
  2380.  
  2381.        POSSIBLE ERROR CONDITION
  2382.        a. Insufficient Memory
  2383.           font number zero will be returned
  2384.           
  2385.        b. Too Many Fonts Loaded
  2386.           The maximum number of fonts allowed to exist simultaneously is
  2387.           a system parameter.  If the number is exceed, font number zero
  2388.           will be returned.
  2389.           
  2390.        c. File Not File
  2391.  
  2392.  
  2393.                                      - 32 -
  2394.  
  2395.  
  2396.  
  2397.  
  2398.  
  2399.        GRAD User's Manual                                    June 7, 1987
  2400.  
  2401.           The  specified  DOS  file  is  not  found.  Font  number  0 is
  2402.           returned.
  2403.           
  2404.        EXAMPLE
  2405.                font1=LoadFont("E9X14.FON");
  2406.  
  2407.        FUNCTIONS INCLUDED
  2408.             RemvFont
  2409.  
  2410.        
  2411.        11.1.2  SelectFont
  2412.  
  2413.                ret=SelectFont(font_number);
  2414.                int ret, font_number;
  2415.  
  2416.        RETURN VALUE
  2417.             If -1  is returned,  it means the font number given does not
  2418.        exist or the font number is not assigned  to  any font. Otherwise
  2419.        the original font number will be returned.
  2420.  
  2421.        DESCRIPTION
  2422.             It selects the current  active font number.  The font number
  2423.        is obtained  from the  function LoadFont except  font number zero
  2424.        which is predefined as the font in BIOS.  It contains pattern for
  2425.        ASCII character 0  to character 127. It is the default font and a
  2426.        permanent font (means always available) in GRAD.
  2427.  
  2428.        EXAMPLE
  2429.                if ((old_font=SelectFont(font_number)) == (-1))
  2430.                        printf("Font %d does not exist\n",font_number);
  2431.                  .   .   .
  2432.                  .   .   .  use font_number as current font
  2433.                  .   .   .
  2434.                SelectFont(old_font);  /* return to original font */
  2435.  
  2436.        FUNCTIONS INCLUDED
  2437.             SelectFrame
  2438.  
  2439.        
  2440.        11.1.3  RemvFont
  2441.  
  2442.                ret=RemvFont(font_number);
  2443.                int ret, font_number;
  2444.  
  2445.        RETURN VALUE
  2446.             A return  value of  0  means  successful.  -1 means the font
  2447.        number does not exist or the font  number is not assigned  to any
  2448.        font.
  2449.  
  2450.        DESCRIPTION
  2451.             It removes the font from  GRAD and the  memory occupied will
  2452.        be deallocated.
  2453.             
  2454.        EXAMPLE
  2455.                if (RemvFont(font_number)==(-1))
  2456.                        printf("Font %d does not exist\n",font_number);
  2457.  
  2458.        FUNCTIONS INCLUDED
  2459.  
  2460.                                      - 33 -
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.        GRAD User's Manual                                    June 7, 1987
  2467.  
  2468.             LoadFont
  2469.  
  2470.        
  2471.        11.1.4  WriteStr
  2472.  
  2473.                WriteStr(options, direction, x, y, string, x_off, y_off);
  2474.                int options, direction, x, y, x_off, y_off;
  2475.                char *string;
  2476.  
  2477.        RETURN VALUE
  2478.             none
  2479.  
  2480.        DESCRIPTION
  2481.             WriteStr is the  most complicated function provided  in GRAD
  2482.        but it is not difficult to use once you understand it. Firstly, I
  2483.        will describe some basic concepts.
  2484.             
  2485.             Each character  in GRAD may be  different size  but they all
  2486.        considered to  be  a rectangular  box,  we called  it a character
  2487.        cell. Size of a character cell is the same for every character in
  2488.        the  fixed size  font file.  But they may be different  for every
  2489.        character in variable size font file.  The width of the character
  2490.        cell  is  called  cell  width and the height  is  called the cell
  2491.        height.  They are parameters  in  the font  file.  Sometimes, the
  2492.        character pattern may be larger  than the character  cell in some
  2493.        special cases but that will be ignored in the time being.
  2494.             
  2495.             There are a total of  seven  parameters  for  WriteStr. They
  2496.        will be described one by one below.  The constants are defined in
  2497.        the include file "GRADIO.H"
  2498.  
  2499.        a. direction  is only  meaningful when AUTO_MOVE options  is used
  2500.           (described  below).  It controls  the direction of  the string
  2501.           printed. Available selections are:
  2502.           LEFT         [default], move left after each character
  2503.           DOWN_LEFT    moves down and left after each character
  2504.           DOWN         moves down after each character
  2505.           DOWN_RIGHT   moves down and right after each character
  2506.           RIGHT        moves right after each character
  2507.           UP_RIGHT     moves up and right after each character
  2508.           UP           moves up after each character
  2509.           UP_LEFT      moves up and left after each character
  2510.           
  2511.        b. options  are divided into 4 sets. They control the referencing
  2512.           point  of  a  character  cell,  clearing  of  character  cell,
  2513.           operation  mode  and  movement  of  text   pointer.  Only  one
  2514.           selection from  each  set can be  used  at  a time. Selections
  2515.           from  different set should  be  combined  using  the  OR ( | )
  2516.           operator. Each set of options will be described separately.
  2517.           
  2518.           A. Referencing  point  options  tells  the  given  point (x,y)
  2519.              located in a character cell. Available selection are:
  2520.              BOTTOM_LEFT   is the default and it  is  most suitable when
  2521.                            direction LEFT is used.
  2522.              BOTTOM_CENTER is most suitable when direction UP or DOWN is
  2523.                            selected.
  2524.              BOTTOM_RIGHT  is  most  suitable  when   direction   UP  is
  2525.                            selected.
  2526.  
  2527.                                      - 34 -
  2528.  
  2529.  
  2530.  
  2531.  
  2532.  
  2533.        GRAD User's Manual                                    June 7, 1987
  2534.  
  2535.              TOP_LEFT      is  most  suitable  when  direction  DOWN  is
  2536.                            selected.
  2537.              TOP_CENTER    is most suitable when direction UP or DOWN is
  2538.                            selected.
  2539.              TOP_RIGHT     is  most  suitable  when  direction  RIGHT is
  2540.                            selected.
  2541.              LEFT_CENTER   is most suitable when direction LEFT or RIGHT
  2542.                            is selected.
  2543.              RIGHT_CENTER  is most suitable when direction LEFT or RIGHT
  2544.                            is selected.
  2545.              
  2546.           B. Clearing  of  Character  Cells.  Although  the  options are
  2547.              provided,  you are not encourage to  use it  and you should
  2548.              avoid  using it  whenever possible.  There are two reasons.
  2549.              First one is the side  effect problem.  Since characters in
  2550.              GRAD may have different sizes. Clearing of a character cell
  2551.              may leave part of  a larger character  under that character
  2552.              cell. Another reason is efficiency problem. If you want the
  2553.              characters  written on a  clear area,  you should clear the
  2554.              whole area  first and then  use  WriteStr  without clearing
  2555.              option. It will be much faster. However, in some situation,
  2556.              use of  this options  is unavoidable so they  are provided.
  2557.              Available selections are:
  2558.              NO_CLEAR      the default.  Do not clear the character cell
  2559.                            before writing.
  2560.              CLEAR_CELL    reset all  the  pixels  within  the character
  2561.                            cell.
  2562.              FILL_CELL     set all the pixels within the character cell.
  2563.              INVERSE_CELL  the effect of this option depends on the plot
  2564.                            type being used.  If plot type 0 is used, the
  2565.                            character cell will be cleared.  If plot type
  2566.                            1 is used, the character cell will be filled.
  2567.                            If  plot type 2  is used,  the character cell
  2568.                            will be inverted.
  2569.           
  2570.           C. Two operation mode is provided. They are:
  2571.              WRITE     the default.  Perform all operations specified in
  2572.                        the other options and then  write  the characters
  2573.                        to the frame.
  2574.              NO_WRITE  Perform  all other operations  specified in other
  2575.                        options but the characters are not written to the
  2576.                        frame.
  2577.              
  2578.           D. Text  pointer movement  options controls the  update of the
  2579.              pointer  after   each  character   is   written.  Available
  2580.              selections are:
  2581.              AUTO_MOVE the default. After writing of character, the text
  2582.                        pointer will be update according to the direction
  2583.                        and  the  cell  height  and  cell  width  of  the
  2584.                        character just written in addition  to the offset
  2585.                        value for x and  y  coordinate  specified  in the
  2586.                        function call.
  2587.              FIX_MOVE  ignore   direction   and   the   character   cell
  2588.                        information.  Update the text pointer  using only
  2589.                        the offset value specified.
  2590.              VAR_MOVE  Update the text pointer using the  user specified
  2591.                        function   in  addition  to   the   offset  value
  2592.                        specified.  This option allows the  user to place
  2593.  
  2594.                                      - 35 -
  2595.  
  2596.  
  2597.  
  2598.  
  2599.  
  2600.        GRAD User's Manual                                    June 7, 1987
  2601.  
  2602.                        the characters wherever he wants. The option will
  2603.                        be  described  in  full  in  the  section  "using
  2604.                        SPACING_FUNC" in the chapter "Advance Topics".
  2605.              
  2606.        c. x and y are the starting coordinates.
  2607.  
  2608.        d. string is a null terminated string which is  printed using the
  2609.           current active font.
  2610.  
  2611.        e. x_off and y_off are the offset  value which will  be  added to
  2612.           the text pointer after each character is written.
  2613.  
  2614.        EXAMPLES
  2615.        1.      WriteStr(0,0,10,100,"This is a test!",0,0);
  2616.        2.      WriteStr(0,0,10,200,"This is a test!",2,0);
  2617.        3.      PlotType(1);
  2618.                WriteStr(TOP_LEFT | SET_CELL,DOWN,10,300,
  2619.                                "This is a test!",0,0);
  2620.  
  2621.             The first example is  the  simplest  form.  It  uses default
  2622.        options.  The second example is the same as the  first one except
  2623.        the spacing between the characters are larger. 2 extra pixels  in
  2624.        the  horizontal  directions are  added to the  text pointer after
  2625.        each  character.  The third  example  will  write  the  string in
  2626.        reverse video from top to down.
  2627.             
  2628.        FUNCTIONS INCLUDED
  2629.             (writec)
  2630.  
  2631.        
  2632.        11.1.5  ReadStr
  2633.  
  2634.                ReadStr(buffer, max_len, startx, starty, mode,
  2635.                                 cursor, end_of_input);
  2636.                char *buffer;
  2637.                int max_len, startx, starty, mode, cursor, end_of_input;
  2638.                
  2639.        RETURN VALUE
  2640.             number of characters entered
  2641.             
  2642.        DESCRIPTION
  2643.             ReadStr reads a line of input from  the keyboard,  echo each
  2644.        character typed and put them into buffer.
  2645.  
  2646.        buffer    is  a character array where the  input  is  stored. The
  2647.                  string  is   null  terminated  and   no  other  control
  2648.                  characters will be stored.
  2649.  
  2650.        max_len   is  the  length  of  the  buffer.   Maximum  number  of
  2651.                  characters can be entered is max_len - 1.
  2652.  
  2653.        startx, starty is  the starting  coordinate  of  the baseline for
  2654.                  echoing the characters entered.
  2655.  
  2656.        mode      controls how the cursor will appear.
  2657.                  NO_CURSOR       no cursor is displayed but the area
  2658.                                  under the cursor is cleared
  2659.                  DISP_CURSOR     just display the cursor
  2660.  
  2661.                                      - 36 -
  2662.  
  2663.  
  2664.  
  2665.  
  2666.  
  2667.        GRAD User's Manual                                    June 7, 1987
  2668.  
  2669.                  BLINK_CURSOR    the cursor character turns on and off
  2670.                  REVERSE_CURSOR  it keeps reversing the cursor
  2671.                  
  2672.                  You may only use one of the above 4 options at a time
  2673.                  but it may combine with the next option.
  2674.                  SHOW_EOI        shows end of input character when
  2675.                                  return is pressed.
  2676.                                  
  2677.        cursor    the character used for cursor
  2678.  
  2679.        end_of_input the character displayed at the end of the line if
  2680.                  SHOW_EOI option is specified in mode.
  2681.  
  2682.             There are  two special key in  ReadStr.  The return key will
  2683.        terminate the input line  and the backspace key  will  delete the
  2684.        last  character typed on  the  line  if  any.  All  other control
  2685.        characters  are ignored.  If  more characters are input  than the
  2686.        buffer can hold, all excess characters will be discarded.
  2687.             
  2688.        EXAMPLE
  2689.                char line[80];
  2690.                ReadStr(line,80,0,100,BLINK_CURSOR | SHOW_EOI, 0x5f, 17);
  2691.  
  2692.             It reads input from  the keyboard  and put  them  into line.
  2693.        Maximum length is 79 characters plus a carriage return.
  2694.  
  2695.        FUNCTIONS INCLUDED
  2696.             writec, WriteStr, HorzLine, PlotType
  2697.  
  2698.        
  2699.        11.1.6  NextXY
  2700.  
  2701.                NextXY(x,y);
  2702.                int *x, *y;
  2703.  
  2704.        RETURN VALUE
  2705.             values  are   returned  in  the   2   parameters.  They  are
  2706.        coordinates for next character in ReadStr and WriteStr.
  2707.             
  2708.        DESCRIPTION
  2709.             NextXY is for ReadStr and WriteStr only. It returns the next
  2710.        coordinate  in  ReadStr  and  WriteStr  if  there   is  any  more
  2711.        characters to  display.  It  should  be  called immediately after
  2712.        ReadStr and WriteStr otherwise the result may be destroyed.
  2713.  
  2714.        EXAMPLE
  2715.                WriteStr(0,0,10,100,"Enter your name : ",0,0);
  2716.                NextXY(&x, &y);
  2717.                ReadStr(line,80,x,y,BLINK_CURSOR,0x5f,0x5f);
  2718.  
  2719.             It print the string "Enter your name : " and then prompt for
  2720.        input immediate after the string.
  2721.  
  2722.        FUNCTIONS INCLUDED
  2723.                none
  2724.  
  2725.  
  2726.  
  2727.  
  2728.                                      - 37 -
  2729.  
  2730.  
  2731.  
  2732.  
  2733.  
  2734.        GRAD User's Manual                                    June 7, 1987
  2735.  
  2736.        12  Block Operations
  2737.  
  2738.             The functions provide ways  to move data  between frames and
  2739.        between frame and external data.  Each block must be a rectangle.
  2740.        When data are  moved to a  GRAD frame,  it can be OR,  AND or XOR
  2741.        with the original data according to the plot type setting.
  2742.             
  2743.             The functions that will be described in this chapter are:
  2744.                BlockCopy       Copy a block between 2 frames
  2745.                BlockSave       Move a block to a disk file
  2746.                BlockLoad       Load a block from a disk file
  2747.  
  2748.        
  2749.        12.1  Function Description
  2750.  
  2751.        12.1.1  BlockCopy
  2752.  
  2753.                ret=BlockCopy(src_frame, src_x, src_y,
  2754.                              dest_frame, dest_x, dest_y,
  2755.                              length, height);
  2756.                int ret, src_frame, src_x, src_y, dest_frame, dest_x;
  2757.                int dest_y, length, height;
  2758.  
  2759.        RETURN VALUE
  2760.             0 means OK. -1 means one of the frame specified is invalid.
  2761.             
  2762.        DESCRIPTION
  2763.  
  2764.             BlockCopy is  used  to  copy  a rectangular  block  from the
  2765.        source frame (src_frame)  to the  destination  frame (dest_frame)
  2766.        specified.  The two frame number can be the same or different but
  2767.        they must  exist at  the time  the call  is  made.  If  the frame
  2768.        numbers are the same,  the source block and the destination block
  2769.        must  not  overlapped  with  each  other  otherwise unpredictable
  2770.        result may be obtained.
  2771.             
  2772.             In  the current implementation,  the  lower 4  bit of dest_x
  2773.        must be  equal to  lower 4  bit of src_x.  If not, BlockCopy will
  2774.        force them to  be equal  by copying the  lower 4  bit of src_x to
  2775.        dest_x.
  2776.             
  2777.             When the block is copied to the destination frame, the block
  2778.        will be OR,  AND or XOR with the original data in the destination
  2779.        block according to the current plot type selected.
  2780.             
  2781.             Both the window setting of the source  and destination frame
  2782.        will affect the size of the block actually copied. BlockCopy will
  2783.        not copy  any data  from  area  outside the window  of the source
  2784.        frame and it will not write to any area outside of  the window of
  2785.        the destination frame.
  2786.             
  2787.             BlockCopy will  not affect  the  current  frame  number. The
  2788.        source and destination frame may be  different  from  the current
  2789.        frame selected.
  2790.             
  2791.        EXAMPLE
  2792.  
  2793.                frame1=CreateFrame(960,480);
  2794.  
  2795.                                      - 38 -
  2796.  
  2797.  
  2798.  
  2799.  
  2800.  
  2801.        GRAD User's Manual                                    June 7, 1987
  2802.  
  2803.                frame2=SelectFrame(frame1);
  2804.                Ellipse(480,240,450,230);
  2805.                BlockCopy(frame1,0,0,frame2,0,0,960,480);
  2806.                
  2807.             Let's assume  the Color Graphics  Adapter display  memory is
  2808.        the original frame selected before execution of the example above
  2809.        and the window size is equal to  frame size.  frame2 will contain
  2810.        the  frame  number  of  the  CGA  frame.  The  length  and height
  2811.        specified in the BlockCopy command is  960  and 480 respectively.
  2812.        However,  the resolution of a CGA is only 640  and 200. Therefore
  2813.        only the upper left corner (640 by 200) of frame1 is copied.
  2814.             
  2815.        FUNCTIONS INCLUDED
  2816.             
  2817.             none
  2818.  
  2819.        
  2820.        12.1.2  BlockSave
  2821.  
  2822.                BlockSave(start_x, start_y, filename, width, height);
  2823.                int start_x, start_y, width, height;
  2824.                char *filename;
  2825.  
  2826.        RETURN VALUE
  2827.             none
  2828.  
  2829.        DESCRIPTION
  2830.             
  2831.             BlockSave will  save  the  block  specified  in  the current
  2832.        active frame to a file with the  given filename.  All data if any
  2833.        in that file will be replaced by the new data.  If that file does
  2834.        not exist, a new file will be created. The coordinates of the top
  2835.        left corner  of  the block is  given by start_x  and start_y. The
  2836.        width and height is specified in the corresponding parameter with
  2837.        the same name.  If the block does  not lay completely  inside the
  2838.        window, only the portion inside the window is saved. If the block
  2839.        is completely outside the window,  no data will be saved  and the
  2840.        file will not be affect if it already exist or the file  will not
  2841.        be created.
  2842.             
  2843.             The actual width and height of  the block will  be stored in
  2844.        the data file also.  The format of the data file is  described in
  2845.        the appendix.
  2846.  
  2847.        EXAMPLE
  2848.  
  2849.                BlockSave(0,0,"test.blk",100,100);
  2850.  
  2851.             Assume the whole block is inside the window,  then the block
  2852.        100 by 100 pixels will be stored in the file "test.blk".
  2853.  
  2854.        FUNCTIONS INCLUDED
  2855.             BlockLoad
  2856.  
  2857.        
  2858.        12.1.3  BlockLoad
  2859.  
  2860.                ret=BlockLoad(start_x, start_y, filename);
  2861.  
  2862.                                      - 39 -
  2863.  
  2864.  
  2865.  
  2866.  
  2867.  
  2868.        GRAD User's Manual                                    June 7, 1987
  2869.  
  2870.                int ret, start_x, start_y;
  2871.                char *filename;
  2872.  
  2873.        RETURN VALUE
  2874.             0  means success. -1 indicates error. It may due to file not
  2875.        found or bad file.
  2876.             
  2877.        DESCRIPTION
  2878.  
  2879.             BlockLoad is the counterpart of BlockSave.  It loads a block
  2880.        file into  the current frame with  the top  left  hand  corner at
  2881.        (start_x,  start_y).  In current implementation, the lower bit of
  2882.        start_x must be equal to the lower 4  bit of the original start_x
  2883.        (in BlockSave)  when  BlockSave is  used.  If not, BlockLoad will
  2884.        force them to match by changing the start_x of BlockLoad.
  2885.             
  2886.             The  way  the  data  is  stored  in  the  current  frame  is
  2887.        controlled by the current plot type. 
  2888.             
  2889.             This is  no  explicit command to load  part of a  block file
  2890.        only.  However,  you may do this by setting the window to exclude
  2891.        part of the block to  be loaded.  No data will  be loaded outside
  2892.        the current window setting.
  2893.             
  2894.        EXAMPLE
  2895.  
  2896.                BlockLoad(400,0,"test.blk");
  2897.  
  2898.        FUNCTIONS INCLUDED
  2899.             BlockSave
  2900.  
  2901.        
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.                                      - 40 -
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.        GRAD User's Manual                                    June 7, 1987
  2936.  
  2937.        13  Frame Printing
  2938.  
  2939.             Before you try to print a frame using the function described
  2940.        in this chapter,  make sure that you have the  correct driver for
  2941.        your printer.  Customizing  of  printer  driver  is  discussed in
  2942.        Appendix A.
  2943.             
  2944.             Since  different   printers  may   use   different  ways  in
  2945.        controlling graphics printing and you may  have different printer
  2946.        driver,  it is impossible to discuss every possible cases. Hence,
  2947.        I would discuss the general situation and use EPSON FX printer as
  2948.        an example.  If you have problem in  understanding,  try to ask a
  2949.        friend who owns  a EPSON FX  or compatible printer to  explain to
  2950.        you.
  2951.             
  2952.             The function that will be explained in this chapter is:
  2953.             
  2954.             PrintFrame
  2955.                Dump the current selected frame to the printer any may
  2956.                overlay with text data.
  2957.  
  2958.             
  2959.             Allowing  the  merge  printing  of  text  and  graphics data
  2960.        greatly  increase  the  speed  of  printing  when  both  text and
  2961.        graphics data are required because  it don't need to  convert the
  2962.        text into graphics data before printing by the program.
  2963.             
  2964.             Use of software printer  spooler can speed up  the printing.
  2965.        Size of the buffer should be 16K bytes or more.
  2966.  
  2967.        
  2968.        13.1  Function Description
  2969.  
  2970.        13.1.1  PrintFrame
  2971.  
  2972.                PrintFrame(options, page, line, line_height, offset);
  2973.                int option, line, line_height, offset;
  2974.                char *page[];
  2975.  
  2976.        RETURN VALUE
  2977.             none
  2978.  
  2979.        DESCRIPTION
  2980.             This function merge print the text data given if any and the
  2981.        current active frame to the printer. The parameters are explained
  2982.        below. The constants can be found in GRADIO.h
  2983.             
  2984.        a. options  consist of  2  sets of  options  for  the  control of
  2985.           vertical  and horizontal  printing  density. Available options
  2986.           depends  on  the printer driver  you have.  The  options given
  2987.           below are for the EPSON FX printer driver.
  2988.           
  2989.           A. Vertical density
  2990.              NORMAL_DOT   The spacing between 2 vertical dot on paper
  2991.                           is equal to the spacing between 2 pins on the
  2992.                           print head in the printer.
  2993.              
  2994.              SMALL_DOT    The spacing between 2 vertical dot is 1/3 of
  2995.  
  2996.                                      - 41 -
  2997.  
  2998.  
  2999.  
  3000.  
  3001.  
  3002.        GRAD User's Manual                                    June 7, 1987
  3003.  
  3004.                           spacing between 2 pins on the print head.
  3005.              
  3006.              I think the best way to explain these is to see an example.
  3007.              The  EPSON FX  printers can print  up to 216  dots per inch
  3008.              vertically.  However, the spacing between pins in the print
  3009.              head is 1/72  inch (3 times of 1/216). In order to print at
  3010.              high  resolution,  the printer spaces 1/216  inch after the
  3011.              first pass  and the  second  pass  and  then  spaces 22/216
  3012.              inches (2/216  +  22/216  =  8/72) and repeat the procedure
  3013.              again.  As a result,  it can print 216  dots vertically per
  3014.              inch.
  3015.              
  3016.              When you specify the SMALL_DOT option, PrintFrame will take
  3017.              advantage of this features and the print the frame  at high
  3018.              resolution. Otherwise, the frame will be printed at 72 dots
  3019.              per inch vertically.
  3020.              
  3021.           B. Horizontal density
  3022.              LOW_DENSITY     The resolution is 60 dots per inch
  3023.              MEDLOW_DENSITY  The resolution is 72 dots per inch
  3024.              MEDIUM_DENSITY  The resolution is 80 dots per inch
  3025.              HIGH_DENSITY    The resolution is 120 dots per inch
  3026.              ULTRA_DENSITY   The resolution is 240 dots per inch
  3027.              
  3028.              Not all EPSON FX  printers  support all of  the above print
  3029.              mode. Read you manual to see which modes are supported.
  3030.              
  3031.        b. page is a pointer to an array of character pointer. PrintFrame
  3032.           gets the text  data using  this pointer.  Also see the example
  3033.           below.
  3034.  
  3035.        c. line is the number of line given in the array pointer by page.
  3036.           If it is zero,  PrintFrame will not look  at page  and no text
  3037.           data overlaid with the frame in printing.
  3038.  
  3039.        d. height  is the number of points between the base  lines of two
  3040.           rows of text data.  A point is defined as the distance between
  3041.           two pins on the print head. For example, the distance two pins
  3042.           on the print head  of  EPSON FX  printer is 1/72  inch. If you
  3043.           want to print at 6  lines per inch,  you should specify 12 (72
  3044.           divided by 6) as height.
  3045.  
  3046.        e. offset  specify  the distance of the first line  of  text data
  3047.           from  the top of  the frame.  offset  is  in term of  point as
  3048.           defined just a second ago. Negative offset means the text data
  3049.           is shifted downward relative to the top of the frame. Positive
  3050.           offset means the text data is shifted upward.
  3051.  
  3052.             
  3053.             The text data and the frame need not be the same  length and
  3054.        width.  However the text data must not longer than 1 line because
  3055.        that will cause auto line feed of the printer and  the  text data
  3056.        must not contain any control codes that will cause  the moving of
  3057.        paper.  There is an exceptional case when the printer is  in near
  3058.        letter quality mode, the printer will automatically line feed for
  3059.        1/216. This is OK.
  3060.             
  3061.        FUNCTIONS INCLUDED
  3062.  
  3063.                                      - 42 -
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.        GRAD User's Manual                                    June 7, 1987
  3070.  
  3071.             none
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.  
  3114.  
  3115.  
  3116.  
  3117.  
  3118.  
  3119.  
  3120.  
  3121.  
  3122.  
  3123.  
  3124.  
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.                                      - 43 -
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.        GRAD User's Manual                                    June 7, 1987
  3137.  
  3138.        14  The DRAW function
  3139.  
  3140.             Draw function provides features similar turtle graphics. The
  3141.        main idea  is  to keep track  of the current coordinates  and use
  3142.        these  coordinate when a function  required  a coordinate number.
  3143.        This help the user to  draw complex figures  without worrying the
  3144.        exact coordinates.
  3145.             
  3146.             The command string for draw  function is very  compact. This
  3147.        also help keeping the program size small.  On the other hand, use
  3148.        of  Draw  functions  will  include  all  GRAD  functions  that is
  3149.        accessible  from Draw at link time even if  you do  not use them.
  3150.        This will increase the executable file size.
  3151.  
  3152.        
  3153.        14.1  Draw
  3154.  
  3155.                Draw(string, parm1, parm2);
  3156.                char *string;
  3157.                int parm1, parm2;
  3158.  
  3159.        RETURN VALUE
  3160.             none
  3161.             
  3162.        DESCRIPTION
  3163.             string is  the  Draw  command  string.  The  syntax  will be
  3164.        described later.  parm1  and parm2 will be assigned to X and Y of
  3165.        marker 0. It will be explained further when we talk about marker.
  3166.        The command string can be any length  but it  has to  be in ASCII
  3167.        and terminated by a NULL character.
  3168.             
  3169.             On entry,  the current environment is saved.  If there is no
  3170.        environment slot  available,  it  is  an  irrecoverable error and
  3171.        program will normally terminated unless a function  is registered
  3172.        for error handling.  On exit,  the  environment  is  not restored
  3173.        automatically.  However,  Draw  provides  an  environment restore
  3174.        command (EO).  You can use it at the end of the command string to
  3175.        restore the environment before exit.
  3176.             
  3177.             The syntax for the command string is given below.
  3178.                :=    stands for define as
  3179.                |     means or
  3180.                [  ]  means this is optional
  3181.                {  }  select one of the entities inside
  3182.          
  3183.          CMD_STRING := CMD_UNITS
  3184.          CMD_UNITS  := CMD_UNIT | CMD_UNIT CMD_UNITS
  3185.          CMD_UNIT   := CMD_CODE[$] [PARAMETERS]
  3186.          CMD_CODE   := LETTER LETTER
  3187.          PARAMETERS := PARAMETER | PARAMETER , PARAMETERS
  3188.          PARAMETER  := DECIMAL | HEXADECIMAL | {&|%}DIGIT{X|Y}
  3189.          DIGIT      := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
  3190.          DECIMAL    := [+|-]DIGITS
  3191.          DIGITS     := DIGIT | DIGITDIGITS
  3192.          HEXDIGIT   := DIGIT | A | B | C | D | E | F | a | b | c | d
  3193.                            | e | f
  3194.          HEXADECIMAL:= 0XHEXDIGITS | 0xHEXDIGITS
  3195.          HEXDIGITS  := HEXDIGIT | HEXDIGITHEXDIGITS
  3196.  
  3197.                                      - 44 -
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.        GRAD User's Manual                                    June 7, 1987
  3204.  
  3205.          LETTER is defined as letter A to Z and a to z
  3206.          
  3207.        If there is  any space separating  any 2  entities  in  the above
  3208.        definition,  it means zero, one or spaces are allowed except when
  3209.        this  is  ambiguity.  For  example,  the  last  parameter  in the
  3210.        preceding CMD_UNIT is  a hexadecimal number.  Since a hexadecimal
  3211.        number may contain a to  f and A to  F which are  also  belong to
  3212.        LETTER.  Therefore it  is necessary  to insert a space  after the
  3213.        last parameter if  that  is  a hexadecimal  number  and  the next
  3214.        CMD_CODE begins with letter a to f or A to F.
  3215.  
  3216.             Below is  a  table  showing  the  command  codes,  number of
  3217.        parameters required,  whether the current coordinates is affected
  3218.        and  a brief description.  P#  (#  represent a digit from 1 to 9)
  3219.        stands for the parameter #.  For example P1  stands for the first
  3220.        parameter.
  3221.  
  3222.        CMD_  no. of  affect
  3223.        CODE  param.  coord.   Description
  3224.        ----  -----   ------   -----------
  3225.         RS     0       No     Reset the window to frame size, logical
  3226.                               origin to physical coordinate 0. The
  3227.                               current coordinates number will change to
  3228.                               reflect the change of the coordinate
  3229.                               system if necessary.
  3230.  
  3231.         LF     1       Yes    move left P1 pixels.
  3232.         RT     1       Yes    move right P1 pixels.
  3233.         UP     1       Yes    move up P1 pixels.
  3234.         DN     1       Yes    move down P1 pixels.
  3235.         UL     1       Yes    move up and left P1 pixels.
  3236.         UR     1       Yes    move up and right P1 pixels.
  3237.         DL     1       Yes    move down and left P1 pixels.
  3238.         DR     1       Yes    move down and right P1 pixels.
  3239.         JR     2       Yes    move left and down P1 and P2 pixels
  3240.                               respectively. P1 and P2 can be negative to
  3241.                               stands for moving right and up.
  3242.         JA     2       Yes    jump to (P1,P2)
  3243.         /* NW and PU only affects the commands */
  3244.         /* LF, RT, UP, DN, UL, UR, DL, DR, JR  */
  3245.                               above                                       
  3246.                               */
  3247.         WR     0       No     write (selects plot type OR)
  3248.         ER     0       No     erase (selects plot type AND)
  3249.         RV     0       No     reverse (selects plot type XOR)
  3250.         NW     0       No     set flag such that when the current
  3251.                               coordinate move, no ink is left on the
  3252.                               frame.
  3253.         PU     0       No     Pen Up for the during next command. The
  3254.                               effect is similar to NW except it only
  3255.                               last for 1 command only.
  3256.         HL     2       Yes    draws a horizontal line starting at
  3257.                               current coordinate and length P1 to the
  3258.                               left and width P2 downward. P1 and P2
  3259.                               cannot be negative.
  3260.  
  3261.  
  3262.  
  3263.  
  3264.                                      - 45 -
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.        GRAD User's Manual                                    June 7, 1987
  3271.  
  3272.         VL     2       Yes    draws a vertical line starting at current
  3273.                               coordinates and length P1 downward and
  3274.                               width P2 to the left. P1 and P2 cannot be
  3275.                               negative.
  3276.         SO     0              set the current position as the new
  3277.                               origin. Current coordinates are set to
  3278.                               zero to reflect change of coordinate
  3279.                               system.
  3280.         SY     1       No     set line style to P1
  3281.         AS     1       No     set arc drawing specification for use by
  3282.                               CI (circle) and EL (ellipse).
  3283.         MK     1       No     put current coordinates into marker P1.
  3284.         MK     3       No     put (P2,P3) into marker P1
  3285.         WN     2       No     the 2 corners of the window is the current
  3286.                               location and (P1,P2).
  3287.         DY     1       No     delay for P1/100 seconds. It is not very
  3288.                               accurate.
  3289.         CI     1       No     current coordinates are the center, P1 is
  3290.                               the radius. It also affected by the arc
  3291.                               specification setting.
  3292.         EL     2       No     current coordinates are the center, P1 is
  3293.                               the length of the horizontal axis and P2
  3294.                               is the length of the vertical axis.
  3295.         RE     2       No     draws a rectangle with upper left corner
  3296.                               at current location and width and height
  3297.                               are P1 and P2 respectively.
  3298.         BX     4       No     draws a box with upper left corner at
  3299.                               current location. Width and height are P1
  3300.                               and P2 respectively. P3 and P4 are the
  3301.                               width of the horizontal and vertical lines
  3302.                               of the box.
  3303.         FC     1       No     draws a solid circle with radius P1
  3304.         FE     2       No     draws a solid ellipse with horizontal and
  3305.                               vertical axes equal to P1 and P2
  3306.                               respectively.
  3307.         ES     0       No     environment variables save into the slot
  3308.                               allocated on entry.
  3309.         EO     1              environment restore from the slot using
  3310.                               parameter P1. KEEP_SLOT is implied. It
  3311.                               does not affect the value of current
  3312.                               coordinates but it may affect the location
  3313.                               of the origin and hence affect the actual
  3314.                               location.
  3315.         FI     0       No     Fill the region starting from current
  3316.                               location.
  3317.  
  3318.             Marker is a  unique feature provided by  draw so it  will be
  3319.        discussed in  detail.  Draw process a total of  10  markers. Each
  3320.        marker can store 2  integer values in the registers called  X and
  3321.        Y.  Coordinate numbers are usually  stored but you  may store any
  3322.        integer values in the marker.  Marker 0 is a special marker which
  3323.        initially values in registers X and Y are  the  second  and third
  3324.        parameters given when Draw is called.
  3325.             
  3326.             There are two ways to retrieve a marker. The first way is to
  3327.        retrieve the absolute value of the markers.  It is done by typing
  3328.        %#X or  %#Y (#  stands  for a digit 0..9)  in the  place  where a
  3329.        parameter is expected. The second way is to retrieve the value of
  3330.  
  3331.                                      - 46 -
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.        GRAD User's Manual                                    June 7, 1987
  3338.  
  3339.        the marker relative to the  current coordinates.  You can do this
  3340.        by typing &#X or &#Y in the place where a parameter  is expected.
  3341.        When the X part is retrieved,  the return value will  be relative
  3342.        to current X coordinate. Similarly when Y part is retrieved.
  3343.             
  3344.             In  the table given above,  some  functions  when  used will
  3345.        affect  the  current  coordinates.  However,  if  you  add  a '$'
  3346.        immediately after the command code,  then the current coordinates
  3347.        will not  be  affected.  Adding  a  '$'  is  only  meaningful for
  3348.        functions that is stated 'Yes' in the table above.
  3349.             
  3350.        EXAMPLE
  3351.                Draw("NW RT6 AS0xc0 EL5,9 UP9 WR RT228",0,0);
  3352.                Draw("NW DN9 AS0x03 EL5,9 RT5 WR DN304",0,0);
  3353.                Draw("NW LF6 AS0x0c EL5,9 DN9 WR LF228",0,0);
  3354.                Draw("NW UP9 AS0x30 EL5,9 LF5 WR UP304",0,0);
  3355.             
  3356.             The above lines will draw a rectangle with round corner.
  3357.             
  3358.        FUNCTIONS INCLUDED
  3359.             Line,  Plottype,  Dot, HorzLine, VertLine, SetStyle, SetOrg,
  3360.        RelOrg,   SetWin,   Circle,  Arc1,  Ellipse,  Earc1,  FillCircle,
  3361.        FillEllipse, EnvSave, EnvRsto, SolidFill, PatternFill.
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.  
  3394.  
  3395.  
  3396.  
  3397.  
  3398.                                      - 47 -
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.        GRAD User's Manual                                    June 7, 1987
  3405.  
  3406.        15  Miscellaneous Functions
  3407.  
  3408.             This chapter will describe  those functions that  do not fit
  3409.        into any other chapter in this manual. It includes:
  3410.                
  3411.                GRADinit        initialize the GRAD environment
  3412.                cleanup         clean up everything before exit
  3413.                XHLine          extend to left and right from a point
  3414.                writec          write a single character
  3415.  
  3416.        
  3417.        15.1  Functions Description
  3418.  
  3419.        15.1.1  GRADinit
  3420.  
  3421.                GRADinit();
  3422.  
  3423.        RETURN VALUE
  3424.             none
  3425.  
  3426.        DESCRIPTION
  3427.             GRADinit  initialize  the  GRAD  environment  and  test  the
  3428.        processor speed and put the  result  into  TEN_MS.  See  also the
  3429.        description of TEN_MS.  It should be called before using any GRAD
  3430.        functions.  Once GRADinit is called, you must call cleanup before
  3431.        exit. Read the description of cleanup in next section.
  3432.             
  3433.        EXAMPLE
  3434.                GRADinit();
  3435.  
  3436.        FUNCTIONS INCLUDED
  3437.             cleanup
  3438.  
  3439.        
  3440.        15.1.2  cleanup
  3441.  
  3442.                cleanup(exit_code);
  3443.                int exit_code;
  3444.  
  3445.        RETURN VALUE
  3446.             none
  3447.             
  3448.        DESCRIPTION
  3449.             cleanup must  be  called  if  GRADinit  was  called.  If the
  3450.        exit_code is non-zero,  cleanup will terminate the  program after
  3451.        clean up using the exit code.  If exit_code is zero, cleanup will
  3452.        return control to the caller.
  3453.             
  3454.        EXAMPLE
  3455.                cleanup(1);
  3456.  
  3457.             Cleans up and terminate the program.
  3458.             
  3459.        FUNCTIONS INCLUDED
  3460.             GRADinit
  3461.  
  3462.        
  3463.  
  3464.  
  3465.                                      - 48 -
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.        GRAD User's Manual                                    June 7, 1987
  3472.  
  3473.        15.1.3  XHLine
  3474.  
  3475.                ret=XHLine(x,y,boundary,leftx,rightx);
  3476.                int x,y,boundary,*leftx,*rightx;
  3477.                int ret;
  3478.  
  3479.        RETURN VALUE
  3480.             -1  is returned  if  (x,y)  is already in  boundary state or
  3481.        (x,y)  is  outside  the  window.  If  return  value  is  not  -1,
  3482.        coordinates of  the left  most and  right most point  of the line
  3483.        drawn are returned in leftx and rightx.
  3484.             
  3485.        DESCRIPTION
  3486.             You give any point (x,y)  and specify the  boundary state in
  3487.        the search.  A horizontal line will be drawn by extending  to the
  3488.        left  and right.  If value of boundary  is 0,  the drawing of the
  3489.        line in that direction stops when it encounters any  pixel in set
  3490.        state.  If the value of  boundary  is non-zero, the drawing stops
  3491.        when it encounters any pixel in  reset state.  The left  most and
  3492.        right  most  coordinates of the  line is returned.  Of course the
  3493.        line cannot go beyond the  window.  All pixels outside the window
  3494.        are considered in boundary state.
  3495.             
  3496.             The line will be drawn  using current plot  type and current
  3497.        line style.  If the point (x,y) is in boundary state, no dot will
  3498.        be drawn and -1 is returned.
  3499.             
  3500.        EXAMPLE
  3501.                VertLine(50,50,100,1);
  3502.                VertLine(150,50,100,1);
  3503.                XHLine(100,100,0,&leftx, &rightx);
  3504.  
  3505.             XHLine  will  draw  a  horizontal  line  from   (51,100)  to
  3506.        (149,100).  51  and  149  will be  returned  in  leftx and rightx
  3507.        respectively.
  3508.             
  3509.        FUNCTIONS INCLUDED
  3510.             none
  3511.  
  3512.        
  3513.        15.1.4  writec
  3514.  
  3515.                writec(x,y,ch,width,height,options);
  3516.                int x,y,ch,*width,*height,options);
  3517.  
  3518.        RETURN VALUE
  3519.             width and height of the character box are  returned in width
  3520.        and height field in the parameter list.
  3521.             
  3522.        DESCRIPTION
  3523.             writec output a single character (ch) using current selected
  3524.        font to the current frame.  (x,y)  is the reference point for the
  3525.        character.  The actual meaning depends on the  options field. The
  3526.        interpretation of  options is  exactly the  same  as  the options
  3527.        field  in  WriteStr  except  it  does  not have  the text pointer
  3528.        movement options (category D).
  3529.             
  3530.             You should avoid using this function as much as possible.
  3531.  
  3532.                                      - 49 -
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.        GRAD User's Manual                                    June 7, 1987
  3539.  
  3540.  
  3541.        EXAMPLE
  3542.                writec(100,100,0x5f,&width, &height, 0);
  3543.  
  3544.        FUNCTIONS INCLUDED
  3545.             WriteStr, HorzLine, PlotType
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.                                      - 50 -
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.        GRAD User's Manual                                    June 7, 1987
  3606.  
  3607.        16  Advance Functions
  3608.  
  3609.             In  this  chapter,  all other  GRAD  functions  that  is not
  3610.        described  in  the preceding chapters  will  be  described. These
  3611.        functions are usually more advance.  Only experience users should
  3612.        try to use them. The functions to be described include:
  3613.             
  3614.                calcaddr        calculate address of the coordinate
  3615.                exchange        exchange the upper and lower byte of int
  3616.                fr_read         read a word from the current frame
  3617.                fr_write        write a word to the current frame
  3618.                phyaddr         calculate physical address 
  3619.                writetype       plot type other than AND, OR and XOR
  3620.  
  3621.        
  3622.        16.1  Functions Description
  3623.  
  3624.        16.1.1  calcaddr
  3625.  
  3626.                addr=calcaddr(x,y);
  3627.                int far *addr;
  3628.                int x,y;
  3629.  
  3630.        RETURN VALUE
  3631.             logical address  where  (x,y)  in  current  active  frame is
  3632.        located.
  3633.             
  3634.        DESCRIPTION
  3635.             It  will  calculate the address  where  the  pixel  (x,y) in
  3636.        current frame is located.  The address return may not be physical
  3637.        address.  You  must  not try to  read  or write  it directly. You
  3638.        should use the functions fr_read and fr_write to read and write.
  3639.             
  3640.        EXAMPLE
  3641.                addr=calcaddr(200,100);
  3642.                if (fr_read(addr) & DOTVALUE[200 & 0x0f]) {
  3643.                    printf("pixel (200,100) is set");
  3644.                } else {
  3645.                    printf("pixel (200,100) is reset");
  3646.                }
  3647.  
  3648.        
  3649.  
  3650.        
  3651.        16.1.2  exchange
  3652.  
  3653.                ret=exchange(value);
  3654.                unsigned int ret, value;
  3655.  
  3656.        RETURN VALUE
  3657.             the upper and lower byte of value is  swapped and  return as
  3658.        function result.
  3659.             
  3660.        DESCRIPTION
  3661.             The upper and lower byte of the parameter is swapped.
  3662.             
  3663.        EXAMPLE
  3664.                printf("%4x\n",exchange(0x1234));
  3665.  
  3666.                                      - 51 -
  3667.  
  3668.  
  3669.  
  3670.  
  3671.  
  3672.        GRAD User's Manual                                    June 7, 1987
  3673.  
  3674.  
  3675.             3412 is the value printed.
  3676.  
  3677.        
  3678.        16.1.3  fr_read
  3679.  
  3680.                ret=fr_read(addr);
  3681.                int far *addr;
  3682.                unsigned int ret;
  3683.  
  3684.        RETURN VALUE
  3685.             the value at the logical address addr
  3686.  
  3687.        DESCRIPTION
  3688.             It  reads the value by  the address given.  You  should only
  3689.        read from  the active frame  otherwise it is not  guaranteed that
  3690.        the result is correct.
  3691.             
  3692.        EXAMPLE
  3693.                addr=calcaddr(200,100);
  3694.                if (fr_read(addr) & DOTVALUE[200 & 0x0f]) {
  3695.                    printf("pixel (200,100) is set");
  3696.                } else {
  3697.                    printf("pixel (200,100) is reset");
  3698.                }
  3699.  
  3700.        
  3701.        16.1.4  fr_write
  3702.  
  3703.                fr_read(addr,value);
  3704.                int far *addr;
  3705.                unsigned int value;
  3706.  
  3707.        RETURN VALUE
  3708.             none
  3709.  
  3710.        DESCRIPTION
  3711.             It write the value into  the address given.  You should only
  3712.        write to the active frame otherwise it is not guaranteed that the
  3713.        result is correct. fr_write use the current plot type in writing.
  3714.             
  3715.        EXAMPLE
  3716.                addr=calcaddr(200,100);
  3717.                fr_write(addr, DOTVALUE[200 & 0x0f]);
  3718.  
  3719.             It writes the pixel (200,100).
  3720.  
  3721.        
  3722.        16.1.5  phyaddr
  3723.  
  3724.                addr=phyaddr(x,y);
  3725.                int x,y;
  3726.                int far *addr;
  3727.  
  3728.        RETURN VALUE
  3729.             physical address of the pixel (x,y) in current active frame.
  3730.  
  3731.        DESCRIPTION
  3732.  
  3733.                                      - 52 -
  3734.  
  3735.  
  3736.  
  3737.  
  3738.  
  3739.        GRAD User's Manual                                    June 7, 1987
  3740.  
  3741.             phyaddr  is  very  similar  to  calcaddr  except  the return
  3742.        address is always a physical address.  If the whole  frame is not
  3743.        accessible  all   the  time  (e.g.   JLASER),  immediately  after
  3744.        execution  of  phyaddr,   the  line  containing   (x,y)  will  be
  3745.        accessible.
  3746.             
  3747.        EXAMPLE
  3748.                int far *addr;
  3749.  
  3750.                addr=phyaddr(x,y);
  3751.  
  3752.        
  3753.        16.1.6  writetype
  3754.  
  3755.                writetype();
  3756.  
  3757.        RETURN VALUE
  3758.             none
  3759.  
  3760.        DESCRIPTION
  3761.             set the plot type to overwrite.  DON'T try to use  it unless
  3762.        you know what you are doing!
  3763.  
  3764.        EXAMPLE
  3765.                writetype();
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.  
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.  
  3783.  
  3784.  
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.                                      - 53 -
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.        GRAD User's Manual                                    June 7, 1987
  3807.  
  3808.        17  System Dependent Functions
  3809.  
  3810.             The functions described in  this  chapter  are  not standard
  3811.        GRAD library functions.  That  means they  are not always  in the
  3812.        library.  It depends on the output device configured in your GRAD
  3813.        system you are using.
  3814.  
  3815.        
  3816.        17.1  Functions Description
  3817.  
  3818.        17.1.1  settext
  3819.  
  3820.                settext();
  3821.  
  3822.        RETURN VALUE
  3823.             none
  3824.             
  3825.        DESCRIPTION
  3826.             It  is  available when  Hercules and Color  Graphics Card is
  3827.        used. The function is to change the display mode to text mode.
  3828.             
  3829.        EXAMPLE
  3830.                settext();
  3831.  
  3832.        
  3833.        17.1.2  setgraph
  3834.  
  3835.                setgraph();
  3836.  
  3837.        RETURN VALUE
  3838.             none
  3839.             
  3840.        DESCRIPTION
  3841.             It is  available when  Hercules  or  Color Graphics  Card is
  3842.        used.  The  function  is to change  the display mode  to graphics
  3843.        mode.
  3844.             
  3845.        EXAMPLE
  3846.                settext();
  3847.  
  3848.        
  3849.  
  3850.        17.1.3  initjlsr
  3851.  
  3852.                initjlsr();
  3853.  
  3854.        RETURN VALUE
  3855.             none
  3856.  
  3857.        DESCRIPTION
  3858.             This is  used  to  initialize  the JLASER  mode  to allocate
  3859.        memory for graphics data. You are not normally required to use it
  3860.        because it is included in GRADinit.
  3861.             
  3862.        EXAMPLE
  3863.                initjlsr();
  3864.  
  3865.        
  3866.  
  3867.                                      - 54 -
  3868.  
  3869.  
  3870.  
  3871.  
  3872.  
  3873.        GRAD User's Manual                                    June 7, 1987
  3874.  
  3875.        17.1.4  cleanjlsr
  3876.  
  3877.                cleanjlsr();
  3878.  
  3879.        RETURN VALUE
  3880.             none
  3881.  
  3882.        DESCRIPTION
  3883.             This is used to clean up the JLASER mode  by deallocate  the
  3884.        memory for graphics data. You are not normally required to use it
  3885.        because it is included in cleanup;
  3886.             
  3887.        EXAMPLE
  3888.                cleanjlsr();
  3889.  
  3890.        
  3891.  
  3892.        17.1.5  dumpjlsr
  3893.  
  3894.                dumpjlsr();
  3895.  
  3896.        RETURN VALUE
  3897.             none
  3898.  
  3899.        DESCRIPTION
  3900.             dumpjlsr will activate JLASER card to dump the memory to the
  3901.        LASER printer.  You may  also  print  the  data  in  memory using
  3902.        PrintFrame.
  3903.             
  3904.        EXAMPLE
  3905.             dumpjlsr();
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.                                      - 55 -
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.        GRAD User's Manual                                    June 7, 1987
  3941.  
  3942.        18  GRAD Global Variables
  3943.  
  3944.             Some of the variables in GRAD may be  used by the  user. You
  3945.        should have at least 2  months of experience with GRAD before you
  3946.        try to use these variables.
  3947.  
  3948.        
  3949.        18.1  TEN_MS
  3950.  
  3951.                int TEN_MS;
  3952.  
  3953.        DESCRIPTION
  3954.             TEN_MS contains  a value that  is proportion to  the central
  3955.        processor speed.  It is only a relative number and  the value may
  3956.        not be the same when GRAD is run twice  in a row  but they should
  3957.        be close.
  3958.             
  3959.             A IBM PC/XT running  at 4.77MHz gives  a count approximately
  3960.        equal to  333.  If  a processor is  ten times  faster,  the value
  3961.        should be about 3330.
  3962.  
  3963.        
  3964.        18.2  DOTVALUE
  3965.  
  3966.                unsigned int DOTVALUE[16]
  3967.  
  3968.        DESCRIPTION
  3969.             DOTVALUE gives the relative  dot position  in  a  word. Each
  3970.        word comprise 16  dots numbered from 0  to 15.  Dot 0 is the left
  3971.        most dot and 15 is the right most dot when display.
  3972.             
  3973.             DOTVALUE[n] where n is number from 0  to 15  gives the value
  3974.        of  the corresponding dot  in  the  word.  See  also  fr_read and
  3975.        fr_write.
  3976.  
  3977.        
  3978.        18.3  PRE_GRAD_ERR_LEVEL, POST_GRAD_ERR_LEVEL
  3979.  
  3980.                int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  3981.  
  3982.        DESCRIPTION
  3983.             The error level in GRAD runs  from 0  to 10. PRE_ERROR_LEVEL
  3984.        defines the  lowest error level  you want to take  control before
  3985.        the  GRAD  default  error  handling  routine  process  the error.
  3986.        POST_ERROR_LEVEL defines  the lowest error level you want to take
  3987.        control  after GRAD  default error  handling  routines  print the
  3988.        error message and before it aborts the program or does recovery.
  3989.             
  3990.             See also PRE_ERROR_FUNC,  POST_ERROR_FUNC and error handling
  3991.        in the chapter "Advance Topics".
  3992.  
  3993.        
  3994.        18.4  PRE_ERROR_FUNC, POST_ERROR_FUNC
  3995.  
  3996.                void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  3997.  
  3998.        DESCRIPTION
  3999.             The declaration of the functions should be like this:
  4000.  
  4001.                                      - 56 -
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.        GRAD User's Manual                                    June 7, 1987
  4008.  
  4009.                
  4010.                #include <stdarg.h>
  4011.                
  4012.                int user_error_routine();
  4013.                extern (*PRE_ERROR_FUNC)();
  4014.                 .
  4015.                 .
  4016.                 .
  4017.                main()
  4018.                {
  4019.                 .
  4020.                 .
  4021.                        PRE_ERROR_LEVEL=4;  /* or the level you want */
  4022.                        PRE_ERROR_FUNC=user_error_routine;
  4023.                 .
  4024.                 .
  4025.                }
  4026.                
  4027.                void user_error_routine(error_level, error_nu, arg_ptr)
  4028.                int error_level, error_nu;
  4029.                va_list arg_ptr;        /* points to additional argument
  4030.                                           from caller */
  4031.                {
  4032.                 .
  4033.                 .
  4034.                }
  4035.                
  4036.             It is similar for POST_ERROR_FUNC.
  4037.  
  4038.        
  4039.        18.5  SPACING_FUNC
  4040.  
  4041.                int (*SPACING_FUNC)();
  4042.  
  4043.        DESCRIPTION
  4044.             This is for used  with  WriteStr.  See the section on "using
  4045.        SPACING_FUNC" in the chapter "Advance Topics".
  4046.             
  4047.  
  4048.        
  4049.        18.6  XLIMIT, YLIMIT
  4050.  
  4051.                int XLIMIT, YLIMIT;
  4052.  
  4053.        DESCRIPTION
  4054.             They are the maximum  physical  coordinates  in  the current
  4055.        frame.  They change when active frame change. You must not change
  4056.        these values.
  4057.  
  4058.        
  4059.        18.7  ORGX, ORGY
  4060.  
  4061.                int ORGX, ORGY;
  4062.  
  4063.        DESCRIPTION
  4064.             (ORGX,  ORGY)  is the  physical coordinate of  the origin in
  4065.        logical coordinate system.
  4066.  
  4067.  
  4068.                                      - 57 -
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.        GRAD User's Manual                                    June 7, 1987
  4075.  
  4076.        18.8  WINX1, WINX2, WINY1, WINY2
  4077.  
  4078.                int WINX1, WINX2, WINY1, WINY2;
  4079.  
  4080.        DESCRIPTION
  4081.             WINX1,  WINX2,  WINY1  and WINY2  stores the lower and upper
  4082.        limit of x coordinate and lower and upper limit  of  y coordinate
  4083.        of the current window respectively.
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.                                      - 58 -
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.        GRAD User's Manual                                    June 7, 1987
  4142.  
  4143.        19  Advance Topics
  4144.  
  4145.        19.1  Error Handling
  4146.  
  4147.             When GRAD functions detects a error,  they will call GRADerr
  4148.        with a error level code and error number.  It will issue an error
  4149.        message and takes appropriate  action. However GRAD also provides
  4150.        a  simple  way for  the  users  to  take  control  when  error is
  4151.        detected. There are four variables declared for error handling:
  4152.  
  4153.                int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  4154.                void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  4155.                
  4156.             Firstly,  let's talk  about the  error  level  in  GRAD. All
  4157.        errors in GRAD is classified into 4  categories -- Warning (level
  4158.        2),  Recoverable Error (level  4),  Unrecoverable Error (level 6)
  4159.        and GRAD Program Error (level 10).
  4160.             
  4161.             The default action in GRAD is to print an error  message for
  4162.        all level of error. If that is a level 2 error (warning), it will
  4163.        return  control to  the program.  Otherwise,  it  will  abort the
  4164.        program.
  4165.             
  4166.             You may change the default action of GRADerr by changing the
  4167.        four variables  mentioned  above.  You  may  take  control before
  4168.        GRADerr  issues  an  error message or  after. PRE_ERROR_LEVEL and
  4169.        POST_ERROR_LEVEL defines the lowest  level of  error you  want to
  4170.        see before GRAD issues an error or after. When GRADerr finds that
  4171.        you want to  take control,  it will call the function  defined in
  4172.        PRE_ERROR_FUNC   or   POST_ERROR_FUNC.   If   PRE_ERROR_LEVEL  or
  4173.        POST_ERROR_LEVEL is  greater than  or  equal to  10 (GRAD Program
  4174.        Error),  user error routine will never be  called. GRADerr always
  4175.        handle level 10 and above error.
  4176.             
  4177.             After functions defined in PRE_ERROR_FUNC or POST_ERROR_FUNC
  4178.        have  processed the error situation,  they may  return control to
  4179.        GRADerr, abort the program by calling cleanup or do a longjmp. If
  4180.        user  program takes control using  PRE_ERROR_FUNC,  error message
  4181.        will not be issued by GRADerr even after it takes  control again.
  4182.        However, both PRE_ERROR_FUNC and POST_ERROR_FUNC may be called if
  4183.        error level is greater than PRE_ERROR_LEVEL and POST_ERROR_LEVEL.
  4184.             
  4185.             There is no way to continue the execution of a GRAD function
  4186.        if it detects a error condition with  error level greater  than 2
  4187.        (warning).
  4188.             
  4189.             Users may define  there own error level and  use  GRADerr to
  4190.        handle that.  In that case, you must write your own user handling
  4191.        routine  or  modify GRADerr  (not recommended).  Below is a short
  4192.        example.
  4193.  
  4194.        
  4195.                #include <stdio.h>
  4196.                #include <GRADVAR.h>
  4197.                #include <stdarg.h>
  4198.                
  4199.                void usererror1(), usererror2();
  4200.                
  4201.  
  4202.                                      - 59 -
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.        GRAD User's Manual                                    June 7, 1987
  4209.  
  4210.                main()
  4211.                {
  4212.                    char line[80];
  4213.                
  4214.                    GRADinit();
  4215.                    setgraph();
  4216.                    PRE_ERROR_LEVEL=4;
  4217.                    PRE_ERROR_FUNC=usererror1;
  4218.                    POST_ERROR_LEVEL=2;
  4219.                    POST_ERROR_FUNC=usererror2;
  4220.                    while (1) {
  4221.                        CreateFrame(960,792);
  4222.                        PlotType(1);
  4223.                        HorzLine(10,280,XLIMIT,25);
  4224.                        PlotType(0);
  4225.                        ReadStr(line,80,10,300,2,0x5f,0x5f);
  4226.                        LoadFont(line);
  4227.                    }
  4228.                }
  4229.                
  4230.                void usererror1(errlevel, errnu, arg_ptr)
  4231.                int errlevel, errnu;
  4232.                va_list arg_ptr;
  4233.                {
  4234.                    extern char *GRADERRMSG[];
  4235.                
  4236.                    printf("I am usererror 1:");
  4237.                    vprintf(GRADERRMSG[errnu],arg_ptr);
  4238.                    printf("\n");
  4239.                }
  4240.                
  4241.                void usererror2(errlevel, errnu, arg_ptr)
  4242.                int errlevel, errnu;
  4243.                va_list arg_ptr;
  4244.                {
  4245.                    printf("I am usererror2\n");
  4246.                }
  4247.                
  4248.             
  4249.             This program will  get error very  soon.  You can  type in a
  4250.        wrong font  file  name  and get a level  2  error.  After several
  4251.        times,  you will get out of memory  error (level  6) because each
  4252.        new frame occupy almost 93K bytes of memory. 
  4253.  
  4254.        
  4255.        19.2  Using SPACING_FUNC
  4256.  
  4257.             The function which address is stored  in SPACING_FUNC should
  4258.        return a integer.  Zero  means go  on.  A  non-zero  values tells
  4259.        WriteStr to stop immediately.  It may also modify  the content of
  4260.        the some of the variables  in WriteStr through the  address given
  4261.        in the parameters.
  4262.             
  4263.             Below is a simple example of using SPACING_FUNC. The spacing
  4264.        between the characters increase by 2 every time.
  4265.                
  4266.                #include <stdio.h>
  4267.                #include <GRADVAR.h>
  4268.  
  4269.                                      - 60 -
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.        GRAD User's Manual                                    June 7, 1987
  4276.  
  4277.                #include <GRADio.h>
  4278.                
  4279.                int increasing();
  4280.                
  4281.                int spacing;
  4282.                
  4283.                main()
  4284.                {  int x,y;
  4285.                
  4286.                   GRADinit();
  4287.                   setgraph();
  4288.                   spacing=0;
  4289.                   SPACING_FUNC=increasing;
  4290.                   WriteStr(VAR_MOVE,0,10,100,
  4291.                           "This is a special test 123456",0,0);
  4292.                   getch();
  4293.                   settext();
  4294.                   cleanup(0);
  4295.                }
  4296.                
  4297.                increasing(curx, cury, w, h, remaining)
  4298.                int *curx, *cury, w, h;
  4299.                char *remaining;
  4300.                {
  4301.                    *curx+=w+spacing;
  4302.                    spacing+=2;
  4303.                    return(0);
  4304.                }
  4305.                
  4306.  
  4307.             The  function increasing will  only get  control if VAR_MOVE
  4308.        option is used in WriteStr.  Every time when it gets  control, it
  4309.        has five  parameters  --  curx,  cury is  the  coordinate  of the
  4310.        reference point of  the character just  written.  w and h are the
  4311.        width and height  of  the character  box  of  the  character just
  4312.        written.  remaining points to the remaining part of the string to
  4313.        be written.  You may modify the remaining part  of  the string on
  4314.        the fly.  For example,  you may set the next character to null so
  4315.        that  WriteStr  will  terminate immediately.  Of  course  you may
  4316.        return a non-zero value to terminate WriteStr too.
  4317.             
  4318.             Another application of SPACING_FUNC is  to do justification.
  4319.        On the first  call  to  WriteStr,  specify  NO_WRITE  and collect
  4320.        information  on  the line.  Then call  WriteStr  again  to insert
  4321.        microspaces to justify the line.
  4322.             
  4323.             Within  SPACING_FUNC,  you  may  call  other  GRAD functions
  4324.        including  WriteStr  too!  But  be  careful,  the  loop  must  be
  4325.        terminate in some way,  otherwise you will get the stack overflow
  4326.        error very soon.
  4327.  
  4328.  
  4329.  
  4330.  
  4331.  
  4332.  
  4333.  
  4334.  
  4335.  
  4336.                                      - 61 -
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.        GRAD User's Manual                                    June 7, 1987
  4343.  
  4344.        20  Sample Programs
  4345.  
  4346.        20.1  MPrint and Interp
  4347.  
  4348.        USAGE
  4349.                MPrint [options] GRAD-command-file text-file-to-be merge
  4350.  
  4351.                Interp GRAD-command-file
  4352.  
  4353.        EXAMPLE
  4354.                Mprint -v1 test.gcm test.txt
  4355.  
  4356.             Print graphics data in high density.
  4357.  
  4358.        DESCRIPTION
  4359.             Below are the simple syntax rules for Interp and Mprint.
  4360.  
  4361.           ` ' means optional, | means or , { } means selection
  4362.  
  4363.           STMT := [ VARIABLE = ] FUNCTION
  4364.           VARIABLE := identifier
  4365.           FUNCTION := identifier ( PARAMETERS ) ;
  4366.           PARAMETERS := PARAMETER , PARAMETERS | PARAMETER
  4367.           PARAMETER := EXPRESSION
  4368.  
  4369.           EXPRESSION := NUMBER | STRING | VARIABLE | & VARIABLE | COLUMN
  4370.                           | LINE
  4371.           NUMBER := +NATURAL | -NATURAL
  4372.           NATURAL := 0xHHHH | decimal digits
  4373.           STRINGS := "character string"
  4374.           H := decimal digits | A | B | C | D | E | F | a | b | c
  4375.                   | d | e | f
  4376.           COLUMN := [ {C|c}NATURAL `, NATURAL' ]
  4377.           LINE := [ {L|l}NATURAL `, NATURAL' ]
  4378.  
  4379.             
  4380.             In  order to  facilitate  the calculation the coordinates on
  4381.        the  paper in  MPrint,  you may specify a coordinate in  terms of
  4382.        line and column number. Both line and column number start from 1.
  4383.        The  calculations  are based on  the character  width  and height
  4384.        setting.  You may change those values using  command line options
  4385.        in Mprint but Interp always use the default values in Mprint.
  4386.             
  4387.             No  variables can be  declared  but there  are  a  number of
  4388.        pre-declared variables.
  4389.          a. temp1,  temp2, temp3, env1, env2, env3, font1, font2, font3,
  4390.             font4,  frame1,  frame2,  frame3,  x1,  x2,  y1,  y2 are all
  4391.             integer variables.
  4392.          
  4393.          b. line is a character pointer to a 132-byte area. It is mainly
  4394.             for ReadStr function.
  4395.          
  4396.          c. pattern1,  pattern2  and pattern3 are pattern definition for
  4397.             use with PatternFill only.
  4398.          
  4399.             
  4400.  
  4401.  
  4402.  
  4403.                                      - 62 -
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.        GRAD User's Manual                                    June 7, 1987
  4410.  
  4411.             '&'  operator can only be used with integer  variables only.
  4412.        Moreover, only integer variables can appear on the left hand side
  4413.        of '=' (assignment).
  4414.             
  4415.             No any kind  of  arithmetic  operations  is  allowed in both
  4416.        Mprint  and  Interp.  However,  you  may  draw  lines  with  same
  4417.        coordinate numbers but at different location by setting origin at
  4418.        different coordinates.
  4419.             
  4420.             PrintPage  in  Interp  is  a  dummy  function.  Execution of
  4421.        PrintPage  in  Interp  will  suspend  the  interpretation  of the
  4422.        command  file  until  any   key  is  pressed  on   the  keyboard.
  4423.        Furthermore, after a key is pressed, the screen will be cleared.
  4424.             
  4425.             PrintPage  in Mprint will  merge print the  current selected
  4426.        frame and the text file if  specified.  The frame will be cleared
  4427.        after printing.
  4428.             
  4429.             MPrint also  provides  a  number  of  options  which  is not
  4430.        provided in Interp. The number inside the parentheses
  4431.             
  4432.           -W   frame width (960)
  4433.           -H   frame height (792)
  4434.           -w   character width in terms of pixels (12)
  4435.           -h   character height in terms of pixels (12)
  4436.           -c   column offset (0)
  4437.           -r   row offset (0)
  4438.           -p   line per page (66)
  4439.           -d   horizontal density (4)
  4440.           -v   vertical density (0)
  4441.           
  4442.             All the default value is for EPSON printer.  You may need to
  4443.        change the default values for different printer.
  4444.             
  4445.             There are a number of examples  for MPrint  and Interp. They
  4446.        illustrate most  of  the features  of Interp and MPrint.  You can
  4447.        learn a lot more about GRAD library by studying those examples.
  4448.  
  4449.        
  4450.        20.2  Rotate
  4451.  
  4452.        USAGE
  4453.                rotate input-FON-file output-FON-file
  4454.  
  4455.        EXAMPLE
  4456.                rotate AMR7.fon AMR7U.fon
  4457.  
  4458.        DESCRIPTION
  4459.             The input and output font file name cannot be the  same. The
  4460.        naming convention is to  append U,  R or D after the  normal font
  4461.        file name  to  indicate  that  font file is  normally for writing
  4462.        upward, to the right or downward.
  4463.             
  4464.             This  program will  rotate  a  font  file  in anti-clockwise
  4465.        direction  for 90  degree.  For example,  AMR7.fon after rotation
  4466.        should have the name AMR7U.fon.  If it is rotated again, the file
  4467.        name should become AMR7R.fon.
  4468.  
  4469.  
  4470.                                      - 63 -
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.        GRAD User's Manual                                    June 7, 1987
  4477.  
  4478.        20.3  Size
  4479.  
  4480.        USAGE
  4481.                size -s# [options] input-file output-file
  4482.  
  4483.        EXAMPLE
  4484.                size -s1 e6x8.fon e12x8.fon
  4485.  
  4486.        DESCRIPTION
  4487.             This program  is  to  change  the  size  of  the  font file.
  4488.        Allowable options are:
  4489.             
  4490.           -s0  reduce height by half
  4491.           -s1  double the height
  4492.           -s2  double the width
  4493.           -m0  ink dominate    (default)
  4494.           -m1  prefer ink
  4495.           -m2  prefer white space
  4496.           -m3  white space dominate
  4497.           
  4498.             -m option is only useful in reducing  the size  of the font.
  4499.        During reduction,  several pixels will be reduced to 1  pixel. If
  4500.        ink donimate option is used,  the resulting pixel is black if any
  4501.        one  of  the source  pixels  is black.  Similarly for white space
  4502.        dominate.  If prefer ink option  is used,  the resulting pixel is
  4503.        black if the number of black pixel is  more than or  equal to the
  4504.        number of white pixel.  If prefer white space option is used, the
  4505.        resulting  pixel is  black if the  number of black pixel  is MORE
  4506.        than the number of white pixel.
  4507.             
  4508.             In  this version  of size,  -m0  and -m1, -m2 and-m3 are the
  4509.        same. In order to provide future compatibility, all 4 options are
  4510.        valid.
  4511.  
  4512.        
  4513.        20.4  DispFont
  4514.  
  4515.        USAGE
  4516.                DispFont
  4517.  
  4518.        DESCRIPTION
  4519.             Enter a font file name when it asks for one. Enter the ASCII
  4520.        code  of  the character you want  to  see.  The character and the
  4521.        enlarger  character will  be  displayed.  A return  or a negative
  4522.        ASCII number will terminate the program.
  4523.  
  4524.        
  4525.        20.5  SwPrt (Sideway)
  4526.  
  4527.        USAGE
  4528.                swprt [options] text-file-name
  4529.  
  4530.        EXAMPLE
  4531.                swprt -fAMR7D.fon -s35 -H1920 -W792 -L3 -v1 -d3 test.txt
  4532.  
  4533.        DESCRIPTION
  4534.             The options provided are: (values inside parentheses are the
  4535.        default value)
  4536.  
  4537.                                      - 64 -
  4538.  
  4539.  
  4540.  
  4541.  
  4542.  
  4543.        GRAD User's Manual                                    June 7, 1987
  4544.  
  4545.            
  4546.            -W  Width of the print out (792).  This is the  length of the
  4547.                frame created for output.  This value should  be a simple
  4548.                fraction (1/2,  1/3 or 1/4) or a integral multiple of the
  4549.                length of paper.  If -v1 (described below) option is used
  4550.                and -L (described below also)  is set to a  value greater
  4551.                than 1,  the width should  be a integral multiple  of the
  4552.                number of  vertical unit per point.  In  other words, for
  4553.                EPSON printer, the value is 3, for OKI Microline 192, the
  4554.                value is 2.
  4555.            
  4556.            -H  Height of the print out (960).  This is the  width of the
  4557.                paper.  This number is related to  the horizontal density
  4558.                (-d option) setting.
  4559.            
  4560.            -v  Vertical  density   (0).   Any  non-zero  value  will  be
  4561.                considered as 1. See PrintFrame for explanation.
  4562.            
  4563.            -d  Horizontal  density   (4).   Also   see   PrintFrame  for
  4564.                explanation.  This value is  suitable  for  EPSON printer
  4565.                only.  You should set it to 2 for OKI printer if you want
  4566.                to use other default values.
  4567.            
  4568.            -s  Spacing between any 2  base line (11). This value is very
  4569.                likely to  be changed  when different font file  is used.
  4570.                See -f option below.
  4571.            
  4572.            -f  Font file  name.  (S6X8D.fon)  This  is the  font used in
  4573.                printing.  When use  other font file,  remember to change
  4574.                the  spacing  between  lines  using  -s  option described
  4575.                above.
  4576.            
  4577.            -t  Top margin (36).  This is the margin on the right side of
  4578.                the paper.
  4579.            
  4580.            -b  Bottom margin (36).  This is the margin on the  left side
  4581.                of the paper.
  4582.            
  4583.            -L  Text length (1). This field controls the number of 'page'
  4584.                for the text.  If text length is set to 2, that means the
  4585.                width of the text is  twice the specified width  (-W). In
  4586.                this way, you may print very long data without creating a
  4587.                very  large frame.  The -L  setting times the  -W setting
  4588.                must  not exceed  30000.  This value should be  more than
  4589.                enough.
  4590.  
  4591.             The default values will print 132 characters by 80 lines per
  4592.        page on a EPSON compatible printer.
  4593.  
  4594.        
  4595.        20.6  Tex2GRAD
  4596.  
  4597.        USAGE
  4598.                TeX2GRAD TeX-PXL-file GRAD-FON-file
  4599.  
  4600.        EXAMPLE
  4601.                TeX2GRAD amr10.pxl amr10.fon
  4602.  
  4603.  
  4604.                                      - 65 -
  4605.  
  4606.  
  4607.  
  4608.  
  4609.  
  4610.        GRAD User's Manual                                    June 7, 1987
  4611.  
  4612.        DESCRIPTION
  4613.             TeX2GRAD  converts  a TeX pixel  files  to  GRAD  font file.
  4614.        During the conversion, ASCII character 32 (' ') is forced to be a
  4615.        space with width equal to 9/16 of the design size.
  4616.             
  4617.             The TeX pixel file must  be a  type 1002  pixel file and the
  4618.        magnification  field in the file  must contain  the resolution of
  4619.        the output  device  the pixel file  is designed for times  5. For
  4620.        example,  a pixel file  for  a  laser  printer  with  300dpi, the
  4621.        magnification  field must contain 1500  decimal.  The pixel files
  4622.        from TEXTSET meets all of the above requirements.
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652.  
  4653.  
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.                                      - 66 -
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.        GRAD User's Manual                                    June 7, 1987
  4678.  
  4679.        Appendix A : Customizing of Printer Control Codes
  4680.  
  4681.        General Information
  4682.  
  4683.             Two printer  drivers  for  EPSON  FX-80  and  OKI  ML192 are
  4684.        distributed  with  the GRAD  library.  If  you have  one of these
  4685.        printers or  a  compatible  one,  you  just  need  to  follow the
  4686.        installation instruction and you will  be  able to print  on your
  4687.        printer. Otherwise, go on reading this chapter.
  4688.             
  4689.             You can only  configure GRAD  to use 8  bit graphics printer
  4690.        with the information here and the included source  files. If your
  4691.        graphics printer is 24-pin printer or it only accepts 7 bit data,
  4692.        you need the source code of GRAD library to do the configuration.
  4693.        Information for special customizing accompany the source code.
  4694.             
  4695.             To do customizing, you need a Microsoft C compiler version 4
  4696.        and you may need a macro assembler also in some cases.
  4697.             
  4698.             There are three files involved in the customizing process.
  4699.          a. prtcntl.c defines the  control  code  sequence  for printing
  4700.             graphics and paper feeding.
  4701.          b. prt.asm  contains routines for converting  data  in frame to
  4702.             data for printing.
  4703.          c. pframe controls  the number  of dots printer  vertically per
  4704.             pass and the number of dots per point.
  4705.          
  4706.             Each  of  these will  be  discussed later.  Firstly,  let me
  4707.        define some  of  the terms first.  A point in  publishing means a
  4708.        length approximately equal to  1/72  inch.  However, a point here
  4709.        means  the distance  between 2  pins on the  print head. Vertical
  4710.        unit  is  the  smallest  distance  that  the  printer   can  move
  4711.        vertically.  The length  of  both  point  and  vertical  unit are
  4712.        printer dependent.  However, a point must be an integral multiple
  4713.        (can be 1) of vertical unit.
  4714.             
  4715.        a. prtcntl.c
  4716.             In prtcntl.c,  there are 8 variables declared. 5 of them are
  4717.        structure prtcmd.  prtcmd is used to store printer  control codes
  4718.        sequence. It contains 5 members.
  4719.             
  4720.             length  the length of the sequence from 0 to 8.
  4721.             factor  the number that will multiple with the number to be
  4722.                     included in the control sequence.
  4723.             numh    the high order byte of the scaled number in the
  4724.                     sequence. The value can be from -1 to length-1. -1
  4725.                     means the high order byte is not used.
  4726.             numl    the low order byte of the scaled number in the
  4727.                     sequence. The value can be from -1 to length-1. -1
  4728.                     means the low order byte is not used.
  4729.             code    the code sequence is stored here. Max. number of
  4730.                     character is 8.
  4731.             
  4732.             GRAD requires 5 kind of control sequences.
  4733.             
  4734.             skp     control sequence for moving the paper forward a
  4735.                     certain number of points. Note, it is point not
  4736.                     vertical unit.
  4737.  
  4738.                                      - 67 -
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.        GRAD User's Manual                                    June 7, 1987
  4745.  
  4746.             skd     control sequence for moving the paper forward a
  4747.                     certain number of vertical unit. Only used when
  4748.                     SMALL_DOT option is used in PrintFrame.
  4749.             setp    set the line feed spacing of the printer to the
  4750.                     specified number of points. It is only used at the
  4751.                     end of PrintFrame to set the printer back to six
  4752.                     line per inch. If skp and skd does not affect the
  4753.                     line feed spacing, you may set setp to null by
  4754.                     setting the length field to 0.
  4755.             header  is a array of struct prtcmd. It contains control
  4756.                     sequence to turn the printer into different density
  4757.                     graphics mode. The sequence is output immediately
  4758.                     before the graphics data.
  4759.             endg    contains the control sequence that append at the end
  4760.                     of graphics data in order to terminate the graphics
  4761.                     mode and cause the printer to actually print out the
  4762.                     data.
  4763.             
  4764.        Other 3 variables are:
  4765.             
  4766.             MAXPSIZ is the maximum number of dots that the printer can
  4767.                     print in different density.
  4768.             NHEADER contains the number of entries in the array header
  4769.                     and MAXPSIZ. Don't forget to change this number when
  4770.                     you change the number of entries in header and
  4771.                     MAXPSIZ.
  4772.             sixlpi  is the value that will be used with setp to set the
  4773.                     printer back to 6 line per inch at the end of
  4774.                     PrintFrame.
  4775.             
  4776.        b. prt.asm
  4777.             It is a assembly  program to  convert data in frame  to data
  4778.        for printing.  The data in a frame is stored line by line and the
  4779.        printer  usually requires  data  to be send  8  (or more) lines a
  4780.        time. prt is the routine for conversion. prtgc is the routine for
  4781.        putting  data  into  the  buffer  and  optionally  do  additional
  4782.        checking for special  pattern.  See  the  case  studies  for more
  4783.        information.
  4784.             
  4785.        c. pframe.obj
  4786.             pframe controls the number  of vertical dots  sent each time
  4787.        and the number of vertical unit per point.  Source code of pframe
  4788.        is  not  included  with  GRAD  library.  However  two  version of
  4789.        pframe.obj is provided: (1) 8 dots each time and 3 vertical units
  4790.        per point (EPSON FX-80) (2) 8 dots each time and 2 vertical units
  4791.        per point (OKI ML192).
  4792.             
  4793.             
  4794.             In the remaining part of the chapter, we will study the code
  4795.        for EPSON printer and OKI printer in  order to  provide a example
  4796.        of customizing.
  4797.  
  4798.        
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.                                      - 68 -
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.        GRAD User's Manual                                    June 7, 1987
  4812.  
  4813.        EPSON FX-80 Driver Case Study
  4814.  
  4815.             IN EPSON FX-80  printer, it does not have a control sequence
  4816.        to forward the paper a specified number  of points.  So I have to
  4817.        set the line spacing to  the desired number  and do  a line feed.
  4818.        The sequence  for setting line spacing is  3  characters long and
  4819.        the fourth character is a line feed.
  4820.             
  4821.             The  length  of  each  vertical  unit is 1/216  inch but the
  4822.        length  of  a point is  1/72  =  3/216 inch. Therefore the factor
  4823.        field is  3  in skp.  Only  a one byte  value is  allowed  in the
  4824.        control sequence so the numh  field is  set to -1  (not used) and
  4825.        numl is set to 2  (the third character).  skd is set in a similar
  4826.        way except the factor field is 1  this time.  If you have a EPSON
  4827.        FX-80  manual,  you would  find  that  the  control  sequence for
  4828.        setting line  spacing is  not the same  as defined  in setp. setp
  4829.        contains two extra characters. These are for IBM graphics printer
  4830.        or compatibles but it should still work for FX-80 printer.
  4831.             
  4832.             EPSON printer requires a length field as part of the control
  4833.        sequence for graphics printing.  It requires the total  number of
  4834.        bytes of graphics data following the sequence.  The  length field
  4835.        is 16 bit. Therefore both the numh and numl fields are set.
  4836.             
  4837.             If your printer don't have 80  dots per inch  mode (640 dots
  4838.        per line on 8 inch paper), you may used the sequence for 240 dots
  4839.        per  inch  and  set  the  factor  field  to  3.  PrintFrame  will
  4840.        automatically insert 2  null characters after  each graphics data
  4841.        byte.
  4842.             
  4843.             endg for EPSON is just a return character.
  4844.             
  4845.             MAXPSIZ values are the number of  dots per inch times  8. If
  4846.        you have a FX-100,  the values should  be the number of  dots per
  4847.        inch times 13.5.
  4848.             
  4849.             If you look at prt.asm,  you would find  that the difference
  4850.        between EPSON and OKI driver is in two main area. Firstly in prt,
  4851.        FX-80  mode use rcl (rotate circular left) while OKI mode use rcr
  4852.        (rotate circular right).  It is because the least significant bit
  4853.        of each byte is printed at the bottom in FX-80  but it is printed
  4854.        at the top in ML192.  Another difference is in prtgc.  OKI has an
  4855.        additional check for 03.  It will be explained in the  case study
  4856.        for OKI ML192.
  4857.  
  4858.        
  4859.        OKI ML192 Driver Case Study
  4860.  
  4861.             OKI ML192  use a  scheme completely different from  FX-80 in
  4862.        printing graphics.  It has control sequence  for forwarding paper
  4863.        without  changing  the line  spacing setting.  Therefore  no setp
  4864.        sequence is  required.  Furthermore,  the line spacing before and
  4865.        after printing is the same and it may not be six line per inch.
  4866.             
  4867.             In ML192, it uses the control code 03 to enter graphics mode
  4868.        and  the sequence  03  02  to  exit from graphics  mode. No total
  4869.        length of  data  is  required  to  send  to  the printer.  If the
  4870.        graphics data  contains the pattern  03,  it has to be duplicated
  4871.  
  4872.                                      - 69 -
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.        GRAD User's Manual                                    June 7, 1987
  4879.  
  4880.        (i.e.  03  03)  to indicate the 03 is a data byte and not command
  4881.        code.  This  is  the   reason  for a special checking  for  03 in
  4882.        prt.asm in OKI mode.
  4883.             
  4884.             endg contains  03  02  to  indicate  end of  data  which are
  4885.        appended at the end of graphics data.
  4886.             
  4887.             sixlpi is not  used in OKI driver.  Therefore it can  be any
  4888.        value but it has to be defined.
  4889.  
  4890.        
  4891.        Additional Information
  4892.  
  4893.             Before you do the customizing,  you should first  try to see
  4894.        any  body  has done  the customizing for  your  printer  make the
  4895.        driver available on the BBS.
  4896.             
  4897.             When  you do  the customizing,  probably you  need to modify
  4898.        prtcntl.c  yourself.  But  you may  not  need  to  modify prt.asm
  4899.        because you may use the OKI or EPSON version.  Then  you choose a
  4900.        suitable version of  pframe  for  your  printer.  If  you  need a
  4901.        special version of pframe, you have to either buy the source code
  4902.        or  see other printer drivers available have  a  version suitable
  4903.        for you or not.  With the source  code and the knowledge of C and
  4904.        assembly language,  customizing for most kind of  printer will be
  4905.        easy. Additional information is provided with source code.
  4906.  
  4907.  
  4908.  
  4909.  
  4910.  
  4911.  
  4912.  
  4913.  
  4914.  
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.                                      - 70 -
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.        GRAD User's Manual                                    June 7, 1987
  4946.  
  4947.        Appendix B : Customizing of Output Device
  4948.  
  4949.             Customizing for output device have a lot  of variations. You
  4950.        may only need to change a single line to rewrite several routines
  4951.        in customizing.  You also need some experiences  with GRAD before
  4952.        trying  to  do  customizing  otherwise  it  is   very  difficult.
  4953.        Therefore  only  general information will  be  given.  You should
  4954.        study the source codes provided yourself to find out what  do you
  4955.        need to change.
  4956.             
  4957.             Three  routines   are  related  to  customizing.   They  are
  4958.        calcaddr.asm,  plottype.asm and ftable.c.  Most  of  the hardware
  4959.        dependent  values  are  defined  in  calcaddr.asm  including  the
  4960.        address of  video memory,  default  font pattern  address and the
  4961.        routines for calculating address  by giving x and  y coordinates.
  4962.        plottype.asm contains the lowest  level memory  accessing routine
  4963.        for reading and writing.  ftable.c contain code for  defining the
  4964.        characteristics of the output device.
  4965.  
  4966.             Three  drivers  are  provided  for  Color  graphics adapter,
  4967.        Hercules graphics adapter (full or half mode) and JLASER card. 
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002.  
  5003.  
  5004.  
  5005.  
  5006.                                      - 71 -
  5007.  
  5008.  
  5009.  
  5010.  
  5011.  
  5012.        GRAD User's Manual                                    June 7, 1987
  5013.  
  5014.        Appendix C : Font File Structure
  5015.  
  5016.             There are 2 types of font files. They are distinguish by the
  5017.        type code  stored  in  each  font  file.  Each  of  them  will be
  5018.        described separately.
  5019.  
  5020.        
  5021.        Fixed Size Character (type 0)
  5022.  
  5023.             The File format is  shown below.  If that field is  a 2 byte
  5024.        integer,  lower byte (less significant)  will be stored first and
  5025.        then the higher  byte  (more significant).  The  word  inside the
  5026.        bracket is the field name.
  5027.             
  5028.           Byte         Description
  5029.           0            ID = 51 decimal
  5030.           1 to n-1     [comment] A string in ASCII terminated by a NULL
  5031.                        character. The string can be any length less than
  5032.                        or equal to 255.
  5033.           n            [type] The type code. 0 in fixed size font file
  5034.           n+1, n+2     [nochar] Number of character in this file
  5035.           n+3, n+4     [start] The starting number. For example, only
  5036.                        pattern for graphic ASCII characters are
  5037.                        available. That means the first pattern is for
  5038.                        ASCII 0x20. Therefore, this field should contains
  5039.                        0x0020.
  5040.           
  5041.           /* the fields below will be described in more detail later */
  5042.           n+5          [width] width of the character cell
  5043.           n+6          [ink-width] ink width of the pattern
  5044.           n+7          [ink-height] ink height of the pattern
  5045.           n+8          [left-margin] left-margin of the pattern
  5046.           n+9          [top-line] the highest line number
  5047.           n+10         [cell-height] height of the character cell
  5048.           n+11         [default] the default character number
  5049.           n+12 to n+15 reserved
  5050.           
  5051.           n+16 to end of file are the pattern information
  5052.           
  5053.             Let's  take  an   example  using  E9X14.fon   (a  font  file
  5054.        containing 9  by 14  patterns). The vales for byte n to byte n+11
  5055.        are:
  5056.             
  5057.             00 00 01 00   00 09 08 0E   00 0A 0E 7F
  5058.             
  5059.             The font file contains pattern in the format of  type 0 (1st
  5060.        byte).  The number of pattern is  256  (0x0100 2nd and 3rd bytes)
  5061.        and it starts it ASCII 0  (0x0000 4th and 5th byte). The width of
  5062.        each  character including spacing  is  9  dots  (0x09  6th byte).
  5063.        However,  only 8  dots (0x08  7th byte)  of data are given in the
  5064.        file  and the pattern given starts  at  the first  dot  (0x00 9th
  5065.        byte).  So  the 9th dots  is assumed to be  0.  The height of the
  5066.        character cell is 14  (0x0E 8th byte).  The pattern starts  at 10
  5067.        lines above the base  line.  That means the descendent  part is 3
  5068.        dots.  If a character given does not have a corresponding pattern
  5069.        in  the file  (greater than 255),  the ASCII  character 255 (0x7f
  5070.        last byte) will be written instead.
  5071.             
  5072.  
  5073.                                      - 72 -
  5074.  
  5075.  
  5076.  
  5077.  
  5078.  
  5079.        GRAD User's Manual                                    June 7, 1987
  5080.  
  5081.             The  pattern is  stored  line  by line according to  the ink
  5082.        width and ink height.  For  example,  a character pattern  of ink
  5083.        width equal to 9 and height equal to 14. 28 bytes are required to
  5084.        store one character.  The character when  display is  in the form
  5085.        below:
  5086.             
  5087.                             0     7 8    15
  5088.                            +-------+-------+
  5089.                            |   0   |   1   |
  5090.                            +-------+-------+
  5091.                            |   2   |   3   |
  5092.                            +-------+-------+
  5093.                              . . . . . . .
  5094.                            +-------+-------+
  5095.                            |   26  |   27  |
  5096.                            +-------+-------+
  5097.                            
  5098.             Only bits 0 to 8 of every 2 bytes are used. 
  5099.  
  5100.        
  5101.        Variable Size Character (type 1)
  5102.  
  5103.             The File format is  shown below.  If that field is  a 2 byte
  5104.        integer,  lower byte (less significant)  will be stored first and
  5105.        then the higher  byte  (more significant).  The  word  inside the
  5106.        bracket is the field name.
  5107.             
  5108.           Byte         Description
  5109.           0            ID = 51 decimal
  5110.           1 to n-1     [comment] A string in ASCII terminated by a NULL
  5111.                        character. The string can be any length less than
  5112.                        or equal to 255.
  5113.           n            [type] The type code. 1 in variable size font
  5114.                        file
  5115.           n+1, n+2     [nochar] Number of character in this file
  5116.           n+3, n+4     [start] The starting number. For example, only
  5117.                        pattern for graphic ASCII characters are
  5118.                        available. That means the first pattern is for
  5119.                        ASCII 0x20. Therefore, this field should contains
  5120.                        0x0020.
  5121.           
  5122.           n+5 to n+7   reserved
  5123.           n+8          [default] the default character number
  5124.           n+9 to n+15  reserved
  5125.           
  5126.           n+16 to n+21 width, ink width, left margin, top line, cell
  5127.                        height information of first character.
  5128.           n+22 to n+27 same kind of information for second character.
  5129.            .
  5130.            .           information of all characters in the file
  5131.            .
  5132.           n+16+6*nochar to end of the file are the pattern data of the
  5133.                        characters
  5134.           
  5135.             The pattern data  are stored  exactly  as  described  in the
  5136.        section  for  fixed  size  character  except  each  character are
  5137.        independent of each other.
  5138.  
  5139.  
  5140.                                      - 73 -
  5141.  
  5142.  
  5143.  
  5144.  
  5145.  
  5146.        GRAD User's Manual                                    June 7, 1987
  5147.  
  5148.        Appendix D : Block File Structure
  5149.  
  5150.             The format  of  a block file  is very simple.  It contains a
  5151.        header and then comes the data. The structure when represented in
  5152.        C syntax is like this:
  5153.             
  5154.                struct header_format {
  5155.                        unsigned char ID;
  5156.                        unsigned int header_length : 4;
  5157.                        unsigned int x_offset : 4;
  5158.                        int length, height;
  5159.                        int dummy;
  5160.                } ;
  5161.                
  5162.                struct blockfile {
  5163.                        struct header_format header;
  5164.                        int data[height][((x_offset+length+15) >> 4)];
  5165.                };
  5166.                
  5167.             The  ID  is  equal   to  101   decimal   in   this  version.
  5168.        header_length is in term of 4-bytes. That means the length of the
  5169.        header must be  multiple of 4  bytes.  The header_length field in
  5170.        block files created by GRAD contain the value 2  now  because the
  5171.        header length is  6  bytes plus 2  byte dummy. The maximum header
  5172.        length is hence 64 bytes. You may include your own information in
  5173.        the header but remember to change the header_length field.
  5174.             
  5175.             We  will return to  x_offset later.  Let's talk about length
  5176.        and  height  fields first.  length and height  contain the actual
  5177.        number  of  pixels  in  the  block  horizontally  and  vertically
  5178.        respectively. 
  5179.             
  5180.             Since the data  array  is  declared  as  integer  array, the
  5181.        number of bytes per line must be even. Since the length field can
  5182.        be any number,  that means some  of the  bits in the data  do not
  5183.        contain  useful  information.  In order to make  the program more
  5184.        efficient,  the starting bit of actual data  of each line  in the
  5185.        file is  the same  as that when  it is in  memory as part  of the
  5186.        frame.  x_offset is used to  store the starting  pixel number for
  5187.        the first word (2  byte) in each line. x_offset may contain value
  5188.        from 0 to 15. 
  5189.             
  5190.             The most significant bit of a byte is displayed  as the left
  5191.        most  pixel of the byte. The earlier bytes of the line are stored
  5192.        at the left of a  frame.  This is the same as Color  Graphics and
  5193.        Hercules Graphics.
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.                                      - 74 -
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.        GRAD User's Manual                                    June 7, 1987
  5214.  
  5215.        Appendix E : Functions Summary
  5216.  
  5217.        Function        Description
  5218.        Arc1            Draws arc (part of a circle)
  5219.        Arc2            Draws arc (part of a circle)
  5220.        ArcPoint        Gives 2 end points of Arc2 or Earc2
  5221.        BlockCopy       Copy a data block between 2 frames
  5222.        BlockLoad       Load a data block from disk
  5223.        BlockSave       Save a data block to disk
  5224.        Box             Draws a box
  5225.        calcaddr        Calculates the word address in byte of a point
  5226.        Circle          Draws a logical circle
  5227.        cleanup         Cleans up everything
  5228.        CopyBlock       Copys a block within or between frame(s)
  5229.        CreateFrame     Creates a new frame
  5230.        Dot             Draws a single dot
  5231.        Draw            Interprete a string of command
  5232.        Earc1           Draws arc (part of an ellipse)
  5233.        Earc2           Draws arc (part of an ellipse)
  5234.        Ellipse         Draws an ellipse
  5235.        EnvSave         Saves the environment
  5236.        EnvRsto         Restores the environment
  5237.        FillCircle      Draws a solid circle
  5238.        FillEllipse     Draws a solid ellipse
  5239.        fr_read         read a word
  5240.        fr_write        write a word according to plot type
  5241.        HorzLine        Draws a horizontal line of any width
  5242.        GRADinit        Initialize GRAD environment
  5243.        Line            Draws a line between any 2 points
  5244.        LoadFont        Loads a font file from disk
  5245.        NextXY          Gives next (x,y) location for ReadStr or WriteStr
  5246.        PatternFill     Fill the area by the pattern specified
  5247.        phyaddr         calculate physical address
  5248.        PlotType        Selects system plot type
  5249.        PrintFrame      Print a frame to Printer
  5250.        ReadStr         Read a line from standard input
  5251.        Rectangle       Draws a rectangle
  5252.        RelOrg          Set origin
  5253.        RemvFont        Removes a font from memory
  5254.        RemvFrame       Removes a frame from GRAD and release the memory
  5255.        ResetWin        Reset the window to the same size as the frame
  5256.        SelectFont      Selects the current font number
  5257.        SelectFrame     Selects the active frame
  5258.        SetOrg          Set origin
  5259.        SetStyle        Sets line style
  5260.        SetWin          Set a rectangular window
  5261.        SolidFill       Entirely fill a region
  5262.        VertLine        Draws a VertLine in any width
  5263.        writec          writes a single character
  5264.        writetype       set to over write
  5265.        WriteStr        writes a string
  5266.        XHLine          A horizontal line extends at both end
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.                                      - 75 -
  5275.  
  5276.  
  5277.  
  5278.  
  5279.  
  5280.        GRAD User's Manual                                    June 7, 1987
  5281.  
  5282.        Appendix F : System Limits
  5283.  
  5284.             There are two types of system limits. First type of limit is
  5285.        caused by  the compiler,  the  algorithms,  the  memory available
  5286.        ...etc.  If one  wants to change these limits,  a  lot of changes
  5287.        have to be made. Another kind of limit is just arbitrary. You may
  5288.        change these limits  by  changing  a constant  and re-compile the
  5289.        program provided you have the source codes, of course.
  5290.  
  5291.        
  5292.        Program Limits
  5293.  
  5294.        a. The  absolute  maximum physical  coordinate must be  less than
  5295.           +32767. In reality, physical coordinate can never get close to
  5296.           this number  because it is limited by  the maximum  frame size
  5297.           also.
  5298.  
  5299.        b. The range of  logical coordinate  must  be  within  -32768 and
  5300.           +32767.
  5301.  
  5302.        c. The maximum horizontal frame size is 4096. You may change this
  5303.           maximum by changing 2  or 3  modules but I think  4096 is more
  5304.           than enough in most cases.  The absolute maximum vertical size
  5305.           is 32767.  But you will run out of memory before you get close
  5306.           to this number.
  5307.  
  5308.        d. The  maximum length  of  the radius  for  Circle,  Arc1, Arc2,
  5309.           FillCircle must be less than 8192.
  5310.  
  5311.        e. For  Ellipse,  FillEllipse,  Earc1 and Earc2, square of one of
  5312.           the axes  times another axis  must  be less then  1E+9. If the
  5313.           length of both axis is the same, maximum length would be 1000.
  5314.           It should be sufficient for most  application except  when you
  5315.           are working on a high resolution output device such  as JLASER
  5316.           and you need a large ellipse.
  5317.  
  5318.        f. There are also limits on the length for HorzLine, VertLine and
  5319.           Line but they are limited by the frame size far before limited
  5320.           by the algorithm.
  5321.  
  5322.        
  5323.        Configuration Limits
  5324.  
  5325.        a. The maximum number of frame that can be exist at the same time
  5326.           including the default  frame  is  10.  This  is  controlled by
  5327.           NFRAME in source listing.
  5328.  
  5329.        b. The maximum number of font that can  be used at  the same time
  5330.           including the  font  in  ROM  is  10.  This  is  controlled by
  5331.           MAXNFONT in source listing.
  5332.  
  5333.        c. The  maximum number  of slot for saving  environment including
  5334.           slot 0 is 10. This is controlled by MAX_ENVSLOT.
  5335.  
  5336.        d. The maximum size of  a single character  is approximately 2000
  5337.           bytes.  That is about 120 by 120 pixels. This is controlled by
  5338.           the size of the array CFBUF.
  5339.  
  5340.  
  5341.                                      - 76 -
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.        GRAD User's Manual                                    June 7, 1987
  5348.  
  5349.        e. The maximum length of data on a single pass for the printer is
  5350.           2048  bytes.  This is also controlled by the size of the array
  5351.           CFBUF.
  5352.  
  5353.        f. There is no arbitrary limit on the length  of  string for draw
  5354.           and WriteStr except by the memory available and the compiler.
  5355.  
  5356.  
  5357.  
  5358.  
  5359.  
  5360.  
  5361.  
  5362.  
  5363.  
  5364.  
  5365.  
  5366.  
  5367.  
  5368.  
  5369.  
  5370.  
  5371.  
  5372.  
  5373.  
  5374.  
  5375.  
  5376.  
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.  
  5403.  
  5404.  
  5405.  
  5406.  
  5407.  
  5408.                                      - 77 -
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.        GRAD User's Manual                                    June 7, 1987
  5415.  
  5416.        Appendix G : Error Messages
  5417.  
  5418.             Below is  a list  of  all  possible  error  message  by GRAD
  5419.        functions.  In a strip down version of error handling routine, it
  5420.        may  only  print the error number.  So the error  number  is also
  5421.        given on the left of the message.
  5422.  
  5423.        Error no.
  5424.           0     "Undefined Error Number : %d"
  5425.           1     "invalid environment slot number in EnvSave - %d"
  5426.           2     "invalid environment slot number in EnvRsto - %d"
  5427.           3     "environment slot not used - %d"
  5428.           4     "disk access error in BlockSave"
  5429.           5     "bad block file"
  5430.           6     "file not found - %s"
  5431.           7     "too many frame opened"
  5432.           8     "not sufficient memory to create new frame - %d*%d"
  5433.           9     "insufficient stack size for Fill"
  5434.          10     "PROGRAM ERROR IN %s LINE %d"
  5435.          12     "bad font type - %d"
  5436.          13     "too many font files loaded"
  5437.          14     "bad font file"
  5438.          15     "not sufficient memory to load new font"
  5439.          16     "no more environment slot for Draw"
  5440.          17     "invalid command in Draw - %c%c"
  5441.          18     "wrong number of parameter given to %c%c in Draw"
  5442.          19     "a digit expected after '%' or '&' in Draw"
  5443.          20     "invalid marker number - %d"
  5444.          21     "disk error in reading font file"
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.  
  5473.  
  5474.  
  5475.                                      - 78 -
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.        GRAD User's Manual                                    June 7, 1987
  5482.  
  5483.        Appendix H : List of Header Files
  5484.  
  5485.             Below is the list of the header files for programs  that use
  5486.        the GRAD library.
  5487.  
  5488.        /*  GRADIO.H  */
  5489.        #define LEFT       0
  5490.        #define DOWN_LEFT  1
  5491.        #define DOWN       2
  5492.        #define DOWN_RIGHT 3
  5493.        #define RIGHT      4
  5494.        #define UP_RIGHT   5
  5495.        #define UP         6
  5496.        #define UP_LEFT    7
  5497.        #define BOTTOM_LEFT     0x00
  5498.        #define BOTTOM_CENTER   0x04
  5499.        #define BOTTOM_RIGHT    0x01
  5500.        #define TOP_LEFT        0x03
  5501.        #define TOP_CENTER      0x06
  5502.        #define TOP_RIGHT       0x02
  5503.        #define LEFT_CENTER     0x05
  5504.        #define RIGHT_CENTER    0x07
  5505.        #define CLEAR_CELL      0x10
  5506.        #define FILL_CELL       0x20
  5507.        #define INVERSE_CELL    0x30
  5508.        #define WRITE           0x00
  5509.        #define NO_WRITE        0x08
  5510.        #define AUTO_MOVE       0x0000
  5511.        #define FIX_MOVE        0x0100
  5512.        #define VAR_MOVE        0x0200
  5513.  
  5514.        /*  GRADARC.h  */
  5515.        #define UP_RIGHT 0x01
  5516.        #define RIGHT_UP 0x02
  5517.        #define RIGHT_DOWN 0x04
  5518.        #define DOWN_RIGHT 0x08
  5519.        #define DOWN_LEFT 0x10
  5520.        #define LEFT_DOWN 0x20
  5521.        #define LEFT_UP 0x40
  5522.        #define UP_LEFT 0x80
  5523.  
  5524.        #define UPPER_HALF 0xc3
  5525.        #define LOWER_HALF 0x3c
  5526.        #define LEFT_HALF 0xf0
  5527.        #define RIGHT_HALF 0x0f
  5528.  
  5529.        void Circle(), Arc1(), Arc2(), FillCircle();
  5530.        void Ellipse(), Earc1(), Earc2(), FillEllipse();
  5531.  
  5532.        /*  GRADENV.h  */
  5533.        int EnvSave(), EnvRsto();
  5534.  
  5535.        #define KEEP_SLOT     0x8000
  5536.        #define KEEP_WIN      0x0001
  5537.        #define KEEP_ORG      0x0002
  5538.        #define KEEP_STYLE    0x0004
  5539.        #define KEEP_PLOTTYPE 0x0008
  5540.        #define KEEP_FRAME    0x0010
  5541.  
  5542.                                      - 79 -
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.        GRAD User's Manual                                    June 7, 1987
  5549.  
  5550.        #define KEEP_FONT     0x0020
  5551.  
  5552.        /*  GRADVAR.h  */
  5553.        extern unsigned int DOTVALUE[];
  5554.        extern int XLIMIT, YLIMIT;
  5555.        extern int ORGX, ORGY;
  5556.        extern int TEN_MS;
  5557.        extern void (*PRE_ERROR_FUNC)(), (*POST_ERROR_FUNC)();
  5558.        extern int (*SPACING_FUNC)();
  5559.        extern int PRE_ERROR_LEVEL, POST_ERROR_LEVEL;
  5560.        extern int WINX1, WINX2, WINY1, WINY2;
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.  
  5575.  
  5576.  
  5577.  
  5578.  
  5579.  
  5580.  
  5581.  
  5582.  
  5583.  
  5584.  
  5585.  
  5586.  
  5587.  
  5588.  
  5589.  
  5590.  
  5591.  
  5592.  
  5593.  
  5594.  
  5595.  
  5596.  
  5597.  
  5598.  
  5599.  
  5600.  
  5601.  
  5602.  
  5603.  
  5604.  
  5605.  
  5606.  
  5607.  
  5608.  
  5609.                                      - 80 -
  5610.  
  5611.  
  5612.  
  5613.  
  5614.