home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / progm / grafx.zip / GRAFX.DOC < prev    next >
Text File  |  1989-05-09  |  19KB  |  449 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                FORTRAN GRAPHIC EXTENSION LIBRARY FOR FORTRAN 77
  8.  
  9.        (C) Copyright 1988, 1989 by Jim Farrell    All Rights Reserved.
  10.  
  11. The GRAFX library  consists of over  50 routines, which  extend ANSI  standard
  12. FORTRAN 77 to access the PC's video display graphics capabilities and SELECTED
  13. DOS services from  FORTRAN programs.  These routines are  used extensively  in
  14. scientific and engineering applications, including:
  15.  
  16.          o  CARTOGRAPHY
  17.          o  ORBITAL MECHANICS
  18.          o  AERODYNAMICS
  19.          o  STATISTICS
  20.          o  OPERATIONS RESEARCH
  21.          o  SIGNAL PROCESSING
  22.  
  23. Emphasis is on ease of use and rapid presentation of numerical data. The GRAFX
  24. library has  proven  to of  great  value  in visual  validation  of  numerical
  25. software algorithms and tools. Hardcopy paper plots can be made on a  graphics
  26. printer by invoking the DOS GRAPHICS  command, then using the SHIFT and  PRINT
  27. SCREEN keys when a copy of the screen is desired.
  28.  
  29. GRAFX is EASY to use! If you use FORTRAN, you can take advantage of your  PC's
  30. video graphics capabilities. The top level  routines were designed to be  easy
  31. to use  and  avoid  features  which  would  add  complexity.  No  training  or
  32. instruction is  required  to use  GRAFX.  The library  and  included  examples
  33. provide everything you  need to  start using your  PC's graphic  capabilities.
  34. GRAFX's simplicity  makes it  ideal for  research &  development,  engineering
  35. prototyping, teaching  of  numerical applications, or as  part of a  numerical
  36. laboratory.
  37.  
  38. GRAFX is compact! While the  entire library is only  about 30K bytes, the  low
  39. level graphic primitive routines take only about one kilobyte. Since GRAFX  is
  40. distributed  in  library  (.LIB)  format,  only  the  required  routines   are
  41. selectively linked with your application.
  42.  
  43. GRAFX is fast! Display memory is  directly manipulated, rather than using  the
  44. slower DOS and BIOS calls to  light pixels. Line and shape drawing  algorithms
  45. were selected to maximize graphic performance.
  46.  
  47. The GRAFX design includes tri-level access to the PC's graphic display. At the
  48. highest level, no knowledge of PC hardware or graphic techniques is  required.
  49. At the middle level, powerful routines  allow creation of custom displays.  At
  50. the bottom level, direct access to display hardware maximizes performance. The
  51. following sections describe each level in detail.
  52.  
  53. TOP LEVEL. At the highest level, the GRAFX library presently provides  several
  54. routines for producing plots.  These routines are  implemented in FORTRAN  and
  55. are hardware independent. These include:
  56.  
  57.        XYPLT - Produces a x-y plot of data. The data is  automatically
  58.        scaled and  displayed.  The  maximum  and  minimum  values  are
  59.        listed. X & Y are passed as real arrays. Up to three plots  may
  60.        be displayed on the screen by successive calls with iv=1..3. Ip
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.        determines the display  type: ip=0, plots  points; ip=1,  plots
  68.        histogram like  lines  from  y=minimum  to  y(i);  ip=2,  plots
  69.        histogram like lines from y=0  to y(i); ip=3, plots from  (0,0)
  70.        to (x,y); ip=4, plots a connected line.  A WARNING is issued if
  71.        the data range  seems inappropriate  for the  selected ip.  The
  72.        usage is:
  73.  
  74.          CALL XYPLT(X,Y,N,IV,IP)
  75.  
  76.        TPLOT -  Produces plots  similar to  XYPLT for  equally  spaced
  77.        data. Only the extreme values of the x range need be  provided.
  78.        TPLOT is useful for time series data. The usage is:
  79.  
  80.          CALL TPLOT(XMIN,XMAX,Y,N,IV,IP)
  81.  
  82.        FCNTPLT -  Produces  plots  similar to  XYPLT  for  a  function
  83.        y=fcn(x). Only the extreme values of the x range and the number
  84.        of points  required need  be provided.  FCNTPLT is  useful  for
  85.        examining the shape of special functions. The function must  be
  86.        declared intrinsic  or external  in  the calling  program.  The
  87.        usage is:
  88.  
  89.          CALL FCNPLT(XMIN,XMAX,FCN,N,IV,IP)
  90.  
  91.          EXTERNAL FCN
  92.  
  93.             or
  94.  
  95.          INTRINSIC FCN
  96.  
  97.        MULPLT -  Sets a  problem space  window and  permits  overlayed
  98.        display of  multiple data  sets through  successive calls.  The
  99.        first call sets the plot limits.
  100.  
  101.          CALL MULPLT0(XMIN,YMIN,XMAX,YMAX)
  102.  
  103.        The second and successive calls pass the arrays to be  plotted,
  104.        the number of points and specify the line style.  IP determines
  105.        the display type  ip=0, plot  a point; ip=1,  plot a  histogram
  106.        like line from y=minimum to  y(i); ip=2, plot a histogram  like
  107.        line from y=0 to  y(i); ip=3, plot from  (0,0) to (x,y);  ip=4,
  108.        plot a connected line.
  109.  
  110.          CALL MULPLT(X,Y,N,IP)
  111.  
  112.        HIST - Computes and displays  a histogram of the   distribution
  113.        of x. The n occurrences of x are counted in 100 equally  spaced
  114.        bins and the maximum occurrence is listed. The usage is:
  115.  
  116.          CALL HIST(X,N)
  117.  
  118.        A typical sequence for using these routines is:
  119.  
  120.          CALL GSET                       !  enter graphics mode
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.          CALL XYPLT(X,Y,N,0,4)           !  draw the plot
  128.          CALL PAUSE('MESSAGE')           !  review plot
  129.          CALL ASET                       !  return to alpha mode
  130.  
  131. As this illustrates, no knowledge of the inner workings and hidden  mechanisms
  132. of PC graphic hardware is required. One loads data into arrays X & Y, switches
  133. to graphic mode and invokes the routine. The call to PAUSE puts the  'message'
  134. on the  bottom  line of  the  display and  waits  until a  key  is  depressed,
  135. permitting time to  review the  plot(s). Returning  to alpha  mode clears  the
  136. screen. The example  programs included on  the installation diskette  contains
  137. examples of the usage of each of the top level routines.
  138.  
  139. MID-LEVEL. The middle  level GRAFX  functions are  invoked by  the high  level
  140. routines. After setting the problem  space window and display space  viewport,
  141. the routines are called using problem  space units. Scaling and conversion  to
  142. the display space viewport is automatic. The mid-level routines are written in
  143. FORTRAN. Two key mid-level routines are:
  144.  
  145.        CALL WINDOW(XPMIN,YPMIN,XPMAX,YPMAX) -  Sets the problem  space
  146.        window. Units are the extremes of the problem at hand: altitude
  147.        in feet, time in seconds, etc. The origin is at the lower left.
  148.        The default range is 0.0 to 1.0 in both x and y. Another way to
  149.        visualize these limits is: CALL WINDOW(LEFT,BOTTOM,RIGHT,TOP).
  150.  
  151.        CALL VIEW((IXDMIN,IYDMIN,IXDMAX,IYDMAX) - set the display space
  152.        viewport. Units are pixels with  the origin at the lower  left.
  153.        The defaults are: x ordinate, 0 to 639; y ordinate, 0 to 199.
  154.  
  155. The use  of WINDOW  and VIEW  to create  multiple displays  on the  screen  is
  156. illustrated  by  the  example  program  VEIW9  included  on  the  distribution
  157. diskette.
  158.  
  159. The following two  mid-level routines  convert from problem  units to  display
  160. units and invoke low level routines to  light points and draw lines.
  161.  
  162.          CALL POINT(X,Y)                 !  DRAW A POINT
  163.          CALL LINE(X1,Y1,X2,Y2)          !  DRAW A LINE
  164.  
  165. LINE is called  in turn by  the following geometrical  shape generators  which
  166. work in problem units.
  167.  
  168.          CALL CIRCLE(X,Y,R)              !  DRAW A CIRCLE
  169.          CALL ARC(X,Y,R,AB,AE)           !  DRAW AN ARC
  170.          CALL BOX(X1,Y1,X2,Y2)           !  DRAW A BOX
  171.          CALL ELLIPSE(X,Y,A,B,ANGLE)     !  DRAW AN ELLIPSE
  172.  
  173. Several auxiliary routines are included  to annotate and control the  display.
  174. PAUSE, ERROR, and  WARN output a  message on the  bottom line and  wait for  a
  175. keystroke. INFO outputs an advisory message on the bottom line and  continues.
  176. The usages are:
  177.  
  178.          CALL CURSOR(ROW,COLUMN)         ! POSITION THE CURSOR
  179.          CALL PUTSTR(ROW,COLUMN,'TEXT')  ! OUTPUT A STRING
  180.          CALL PAUSE('MESSAGE')           ! WAITS FOR A KEYSTROKE
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.          CALL ERROR('MESSAGE')           ! WAITS FOR A KEYSTROKE
  188.          CALL WARN('MESSAGE')            ! WAITS FOR A KEYSTROKE
  189.          CALL INFO('MESSAGE')            ! DOES NOT WAIT FOR A KEYSTROKE
  190.  
  191. The middle level GRAFX routines provide  the tools to create custom plots  for
  192. specific applications. Limit checking of points  and clipping of lines is  not
  193. done. It  is assumed  that  the user  has  defined appropriate  problem  space
  194. limits. A  clipping  routine  is  provided in  the  library  for  applications
  195. requiring clipping.
  196.  
  197. LOW LEVEL. At the  lowest level GRAFX consists  of subroutines implemented  in
  198. INTEL 8086/88 assembly language.  These routines provide the  FORTRAN/assembly
  199. language interface, invoke  DOS and  BIOS services, perform  vector to  raster
  200. conversion, and directly draw points and lines in the graphic display  memory.
  201. These routines use sixteen bit arguments (INTEGER*2) and IBM screen coordinate
  202. conventions. Their use requires a fairly detailed understanding of the PC.
  203.  
  204.          CALL GSET               ! enter graphic mode
  205.          CALL GCLS               ! clear graphic memory
  206.          CALL ASET               ! enter alpha mode
  207.          CALL ACLS               ! clear alpha memory
  208.          CALL PSET(X,Y)          ! turn on the pixel at x,y
  209.          CALL PCLR(X,Y)          ! turn off the pixel at x,y
  210.          PTST(X,Y)               ! test the pixel at x,y
  211.          CALL PLINE(X1,Y1,X2,Y2) ! draw line
  212.          CALL PCURSO(ROW,COLUMN) ! position the cursor
  213.          CALL PUTCH(CH)          ! put a character
  214.          CALL BEEP               ! beep the speaker
  215.          CALL REPLY              ! wait for a keyboard entry
  216.          CALL LCLR               ! clear to end of line
  217.  
  218. MISCELLANEOUS ROUTINES.  Many  miscellaneous  routines  are  included  in  the
  219. library. These provide  bit level access,  shift, and logical  (AND, OR,  NOT,
  220. EOR) operations required by some applications. A standard pseudo-random number
  221. generator is included in the GRAFX  library to support the examples.  Routines
  222. to get time-of-day, time in seconds, and date are included. A vector  clipping
  223. routine is included which can  be used to clip  a problem space vector  before
  224. calling LINE. If you really want to get down to the bits and bytes PEEK & POKE
  225. routines are included to access any location in the 8086 address space.
  226.  
  227. Programmer notes provide the details on how  to use each routine in the  GRAFX
  228. library, recommendations  on  preferred usage,  and  warnings on  pitfalls  to
  229. avoid. GRAFX programmer notes  are in the file  NOTES.DOC on the  distribution
  230. diskette.
  231.  
  232. COMPATIBILITY. GRAFX  uses the  IBM CGA   "high-resolution"  640 X  200  pixel
  233. monochrome graphics (mode 6). CGA is  the most widely available graphics  mode
  234. on the PC. While CGA graphics has several design limitations, including a non-
  235. square pixel/aspect ratio, lack of a scalable graphic character set, and a low
  236. vertical resolution, GRAFX compensates by generating shapes in problem  space.
  237. The (optional)  use of  a 8087  numeric coprocessor  makes the  conversion  to
  238. display space  efficient (about  20X faster).  Further line  drawing speed  is
  239. achieved through the use  of assembly language routines  to perform vector  to
  240. raster conversion and directly manipulate display memory instead of using BIOS
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247. & DOS INT  services. These routines  have been tested  with the IBM  PC/XT/AT,
  248. clones and compatibles with and without numeric coprocessors.
  249.  
  250. GRAFX is a  FORTRAN extension  that can  save you  time and  money in  solving
  251. problems and  communicating results.  GRAFX is  ideal for  academic  computing
  252. where programming  the incidental  means to  an end  (e.g. teaching  numerical
  253. methods) and for prototyping of engineering systems. Several complete examples
  254. are  included.  Additional  library  routines  are  available  which   support
  255. geographic  displays,  numerical  analysis,  orbital  mechanics,and  numerical
  256. simulations.  For  further  details,  custom  requirements,  and  source  code
  257. availability; contact:
  258.  
  259.                                  Jim Farrell
  260.                                 Ridge Technology
  261.                               1867 Park Road, N.W.
  262.                              Washington, D.C. 20010
  263.                                  (202) 232-1441
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.                           GRAFX DISTRIBUTION POLICY
  273.  
  274.        (C) Copyright 1988, 1989 by Jim Farrell    All Rights Reserved.
  275.  
  276. GRAFX is the property of Jim  Farrell and is distributed by RIDGE  TECHNOLOGY.
  277. Individuals are  granted a  limited license  to  use GRAFX,  and to  copy  and
  278. distribute it, provided that the following conditions are met:
  279.  
  280.       1) No fee may be charged, except a nominal fee to cover duplication
  281.       and mailing costs.
  282.  
  283.       2)  The  GRAFX  library  and   documentation  files  may  ONLY   be
  284.       distributed in their original, unmodified state.
  285.  
  286.       3) GRAFX may not be  distributed, in whole or  in part, as part  of
  287.       any commercial or government product or service without the express
  288.       written permission of Jim Farrell.
  289.  
  290. If you use this program on a regular basis register your copy. By  registering
  291. your copy, you will:
  292.  
  293.    o  Receive a CURRENT copy of the distribution diskette
  294.    o  Get one year of technical support - by phone or written
  295.    o  Be notified of updates & new products
  296.    o  Provide input and ideas to help shape future products
  297.    o  Help to keep software prices down, by supporting a
  298.       distribution method which doesn't rely on expensive
  299.       advertising campaigns.
  300.  
  301. GRAFX is user supported software. This means  that you may copy it freely  and
  302. give the  copies to  anyone you  wish, at  no cost.  They, in  turn, are  also
  303. requested to register their copy if they decide to use it.
  304.  
  305. The user supported  software concept (often  referred to as  shareware) is  an
  306. attempt to provide wide distribution of software at a low cost. It reduces the
  307. cost of offering a new product, and hence permits many independent authors and
  308. small companies to develop and promote products  to meet the many needs of  PC
  309. owners. User supported software is a new marketing channel, where products can
  310. be introduced at low cost.
  311.  
  312. With user supported software, everyone  benefits. The user benefits by  having
  313. access to quality products at low cost,  and is able to "test drive"  software
  314. thoroughly before purchasing it.  The author benefits by  being able to  enter
  315. the commercial software arena without  first needing large sources of  venture
  316. capital.
  317.  
  318. The method only works with  your support. Not just  for this product, but  all
  319. user supported software. If you obtain a user supported program from a  friend
  320. or colleague, and are still using it after a couple of weeks, it is  obviously
  321. worth something to you, and it should be registered.
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.                            SITE LICENSE AGREEMENTS
  331.  
  332. Commercial and government  users must  obtain a site  license for  the use  of
  333. GRAFX. Use  the order  form in  this manual  to obtain  a site  license.  Site
  334. licenses are granted as of  when we receive your  payment. Enclosed is a  site
  335. license agreement, which  should be  signed and  sent with  your payment  when
  336. ordering a government  or commercial  site license.  A site  license does  not
  337. include additional copies  of the  GRAFX program  disk and  the GRAFX  manual.
  338. Instead, you make your own copies of the disk and  manual as you need them. If
  339. you wish, you can order additional program  disks from us. See the order  form
  340. included for more details.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.                         PROGRAM SITE LICENSE AGREEMENT
  349.  
  350. Jim  Farrell  provides  this  program   and  licenses  its  use.  You   assume
  351. responsibility for  the selection  of  the program  to achieve  your  intended
  352. results, and  for the  installation, use  and the  results obtained  from  the
  353. program.  The  use  of  GRAFX  in  a  commercial  environment  or   government
  354. organization is granted under the following terms:
  355.  
  356.      1.  Payment of the license fee must be made to Jim Farrell. The  fee
  357.      is based on the number of computers on which GRAFX will be used,  as
  358.      follows:
  359.  
  360.               1 to  9 computers  $35 each
  361.              10 to 24 computers  $25 each
  362.              25 to 49 computers  $20 each
  363.              50 to 99 computers  $15 each
  364.              over  99 computers  $1500 one time fee
  365.  
  366.      2.  You may  use GRAFX on  the number of  computers included in  the
  367.      license fee. If you  have paid the fee  for over 99 computers,  then
  368.      you may  use  GRAFX  on  any  number of  computers    within    your
  369.      organization.
  370.  
  371.      3.  You may make copies  of the program and documentation, in  their
  372.      original, unmodified form, without  restriction. You may  distribute
  373.      these copies without restriction.
  374.  
  375.      4.  If these  copies are distributed  outside of your  organization,
  376.      you have no obligation to control the use of those copies which  are
  377.      outside of your organization.
  378.  
  379.      5.  You may not  modify the program or charge  a fee for copying  or
  380.      distributing the program or its documentation.
  381.  
  382.      6.  It is  your responsibility to make  the necessary copies and  to
  383.      deliver them to  the computers which  they will be  used on. If  you
  384.      wish, you can order additional GRAFX distribution diskettes.
  385.  
  386. I agree to abide by the terms and conditions of this license.
  387.  
  388.  
  389.         _____________________________         _________________
  390.         Signature                             Date
  391.  
  392.         _____________________________
  393.         Name (please print or type)
  394.  
  395.         _____________________________
  396.         Title
  397.  
  398.         _____________________________
  399.         Company
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.                        ORDER FORM
  408.  
  409.         Check which items you wish to purchase:
  410.  
  411.         [] Non-commercial license for the use of GRAFX at $29.95.
  412.         [] Commercial license for the use of GRAFX on ___ computers (see
  413.            attached price schedule and terms).
  414.         [] Distribution disk with documentation (only on orders of
  415.            $50.00 or more, not counting maintenance contracts).
  416.         [] ____ additional disks at $10.00 per disk.
  417.         [] One year maintenance agreement at $50.00 per year.
  418.  
  419.         [] Payment of $ ____.__ is enclosed (check or money order).
  420.  
  421.  
  422.         _________________________________________
  423.         Name
  424.  
  425.         __________________________________________
  426.         Address
  427.  
  428.         _______________________  _____  __________
  429.         City                     State     Zip
  430.  
  431.  
  432.         Mail this completed form with payment to:
  433.  
  434.            Jim Farrell
  435.            RIDGE TECHNOLOGY
  436.            1867 Park Road, N.W.
  437.            Washington, D.C. 20010
  438.  
  439.         Phone: (202) 232-1441
  440.  
  441.         For  program  disk  orders  outside  the  U.S.,  please  add   an
  442.         additional $5, and enclose  an international money order  payable
  443.         in U.S. currency.
  444.  
  445.         For commercial site license orders, please enclose a signed  copy
  446.         of the site license agreement.
  447.  
  448.  
  449.