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