home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / progm / grafx.zip / NOTES.DOC < prev    next >
Text File  |  1989-03-21  |  20KB  |  470 lines
  1. .-
  2. GRAFX PROGRAMMER NOTES
  3.  
  4. (C) Copyright 1988, 1989 by Jim Farrell      All Rights Reserved.
  5.  
  6. GRAFX is a FORTRAN extension library of over 50 routines which gives
  7. the FORTRAN user access to the PC's graphic video display and a
  8. selection of DOS and BIOS services. GRAFX can save you time and money
  9. in solving problems and communicating results.  Several complete
  10. examples are included.
  11.  
  12. The following notes provide information on how to call the GRAFX
  13. library subroutines and functions. Most usage and conventions can be
  14. determined from studying the example programs included on the the
  15. distribution diskette.
  16.  
  17. -----------------------------------------------------------------------
  18. TOP LEVEL ROUTINE NOTES
  19. -----------------------------------------------------------------------
  20.  
  21. The following routine uses the lower level routines to produce a x-y
  22. plot display.
  23. -----------------------------------------------------------------------
  24. call xyplt(x,y,n,iv,ip)        !  produce x-y plots 
  25.  
  26. real x(*),y(*)
  27.  
  28. A quick look x-y plot routine (scatter plot). Up to three plots may be
  29. displayed on the screen by calling with IV=1..3. If 1 > IV > 3 then a
  30. full screen plot is displayed. IP determines the display type IP=0,
  31. plot a point; IP=1, plot a histogram like line from y=minimum to y(i);
  32. IP=2, plot a histogram like line from y=0 to y(i); IP=3, plot from
  33. (0,0) to (x,y); IP=4, plot a connected line.  A WARNING is issued if
  34. the data range is inappropriate for the selected IP.
  35.  
  36. -----------------------------------------------------------------------
  37. The following routine uses the lower level routines to display equally
  38. spaced samples (e.g. time series) display.
  39. -----------------------------------------------------------------------
  40. call tplot(xmn,xmx,y,n,iv,ip)        !  produce y=f(t) plots 
  41.  
  42. real y(*)
  43.  
  44. A quick look y=f(t) plot routine for equally spaced data.  Up to three
  45. plots may be displayed on the screen by calling with IV=1..3; Any other
  46. value of IV yields a full screen plot. IP determines the display type
  47. IP=0, plot a point; IP=1, plot a histogram like line from y=minimum to
  48. y(i); IP=2, plot a histogram like line from y=0 to y(i); IP=3, plot
  49. from (0,0) to (x,y); IP=4, plot a connected line. A WARNING is issued
  50. if the data range is inappropriate for the selected IP. See example
  51. program for a demonstration of line drawing types.
  52.  
  53. -----------------------------------------------------------------------
  54. The following routine uses the lower level routines to display
  55. intrinsic or external functions.
  56. -----------------------------------------------------------------------
  57. call fcnplt(xmn,xmx,fcn,n,iv,ip)        !  produce y=fcn(x)
  58.  
  59. external fcn
  60.    or
  61. intrinsic fcn
  62.  
  63. A quick look y=fcn(x) plot routine for n points over a range of x.  Up
  64. to three plots may be displayed on the screen by calling with IV=1..3;
  65. Any other value of IV yields a full screen plot. IP determines the
  66. display type IP=0, plot a point; IP=1, plot a histogram like line from
  67. y=minimum to y(i); IP=2, plot a histogram like line from y=0 to y(i);
  68. IP=3, plot from (0,0) to (x,y); IP=4, plot a connected line. A WARNING
  69. is issued if the data range is inappropriate for the selected IP. See
  70. example program for a demonstration of line drawing types.
  71.  
  72. -----------------------------------------------------------------------
  73. The following routine uses the lower level routines to produce multiple
  74. plot display.
  75. -----------------------------------------------------------------------
  76. subroutine mulplt0(xmn,ymn,xmx,ymx)
  77.  
  78. ...initialize limits for multiple x-y plots
  79.  
  80. A WARNING is issued if the data range is inappropriate for the selected
  81. IP.
  82.  
  83. subroutine mulplt(x,y,n,ip)        !  produce multiple x-y plots
  84.  
  85. real x(*),y(*)
  86.  
  87. A multiple x-y plot routine. IP determines the display type IP=0, plot
  88. a point; IP=1, plot a histogram like line from y=minimum to y(i); IP=2,
  89. plot a histogram like line from y=0 to y(i); IP=3, plot from (0,0) to
  90. (x,y); IP=4, plot a connected line.
  91.  
  92. -----------------------------------------------------------------------
  93. The following routine uses the lower level routines to support
  94. histogram display.
  95. -----------------------------------------------------------------------
  96. call hist(x,n)                !  plot histogram 
  97.  
  98. real x(*)
  99.  
  100. ...routine to plot a histogram of the distribution of x. The n
  101. occurrences of x are counted in 100 equally spaced bins. The results are
  102. then displayed graphically.
  103.  
  104. -----------------------------------------------------------------------
  105. MID LEVEL ROUTINE NOTES
  106. -----------------------------------------------------------------------
  107. GRAFX uses two include files internally:
  108.  
  109. "physcon.icl" - physical constants
  110.  
  111. "grafcom.icl" - graphic common
  112.  
  113. These are included on the distribution diskette.
  114.  
  115. Physcon.icl contains the constant PI, conversions from radians to
  116. degrees, and earth physical constants.
  117.  
  118. Grafcom.icl contains the named COMMON /GRAFCOM/ which contains the
  119. information to map between display space and problem space.
  120.  
  121. -----------------------------------------------------------------------
  122. Unless otherwise noted, GRAFX assumes that the default implicit FORTRAN
  123. conventions are:
  124.  
  125. integer*4 and real*4.
  126.  
  127. -----------------------------------------------------------------------
  128. A BLOCK DATA module GRAFINIT initializes the problem space window to
  129. 0.0 to 1.0 in both x and y. It initializes the display space view to 0
  130. to 639 in the x direction and 0 to 199 in the y direction. Invocation
  131. of either WINDOW or VIEW force the loading of GRAFINIT from the
  132. library. If you choose to use the default problem and display space
  133. parameters without invoking either WINDOW or VIEW, the BLOCK DATA
  134. "GRAFINIT" must be declared "external" in your program to force loading
  135. it from the library.
  136.  
  137. -----------------------------------------------------------------------
  138. call window(xmn,ymn,xmx,ymx)        !  set problem space window
  139.  
  140. Set problem space window (left, bottom, right, top) in named COMMON
  141. /GRAFCOM/. Origin is lower left. Next call view with display space
  142. view. The defaults are 0.0 and 1.0 for bottom, left and top, right
  143. respectfully.
  144.  
  145. -----------------------------------------------------------------------
  146. call view(xmn,ymn,xmx,ymx)        !  set display space view
  147. integer xmn,ymn,xmx,ymx
  148.  
  149. Set display space window view (left, bottom, right, top) in named
  150. COMMON /GRAFCOM/.  The default is 0 to 639 for x and 0 to 199 for y.
  151. Arguments are screen coordinates (pixels).  Note that the GRAFX
  152. convention is for the origin in the lower left corner of the screen.
  153. ymn is the lower coordinate and ymx is the upper.
  154.  
  155. -----------------------------------------------------------------------
  156. -----------------------------------------------------------------------
  157. The following routines are the mid-level problem space point, line, and
  158. shape generators.  To compensate for the CGA non-linearities, shapes
  159. are generated in problem space. The (optional) use of a 8087 numeric
  160. coprocessor makes the conversion to display space efficient (about 20X
  161. faster than with no 8087). Further line drawing speed is achieved
  162. through the use of assembly language routines to perform vector to
  163. raster conversion and direct manipulation display memory instead of
  164. using BIOS & DOS INT services. Limit checking of points and clipping of
  165. lines is not done. It is assumed that the user has defined appropriate
  166. problem space limits. A clipping routine is provided in the library for
  167. applications requiring clipping.
  168.  
  169. -----------------------------------------------------------------------
  170. call point(xp,yp)        ! light a pixel in problem space
  171.  
  172. Converts problem coordinates to display coordinates and calls pset to
  173. light the pixel.
  174.  
  175. -----------------------------------------------------------------------
  176. call color('BLACK')
  177.  
  178. Determine the color of lines. The default is 'WHITE' or on. In CGA
  179. hi-res mode, there are only two possibilities. 'BLACK' turns off pixels
  180. that are lit and can be used to erase lines.
  181.  
  182. -----------------------------------------------------------------------
  183. call line(xp1,yp1,xp2,yp2)        !  draw a problem space line (P1 ->
  184. P2)
  185.  
  186. Converts problem coordinates to display coordinates and calls pline to
  187. draw the line.
  188.  
  189. -----------------------------------------------------------------------
  190. call plot(x,y,ip)            !  move to problem space point P
  191.  
  192. Converts the problem coordinate to a display coordinate and moves from 
  193. the current position to x,y. If ip = 2 a line is drawn. This routine is
  194. included to provide compatibility with CALCOMP style calls. Tests have
  195. shown no speed advantage over subroutine line.
  196.  
  197. -----------------------------------------------------------------------
  198. call box(x1,y1,x2,y2)        !  draw a problem space box
  199.  
  200. Call line to draw the box. P1 is lower left. P2 is upper right.
  201.  
  202. -----------------------------------------------------------------------
  203. call circle(x,y,r)        !  draw a problem space circle 
  204.  
  205. Uses recursive trigonometric techniques to draw a 64 line segment
  206. circle in problem space. Only four multiplies and six additions are
  207. inside the computational loop. X and y are the center point. R is the
  208. radius.
  209.  
  210. -----------------------------------------------------------------------
  211. call arc(x,y,r,ab,ae)        !  draw a problem space arc
  212.  
  213. Uses a technique similar to the circle routine to draw an arc.
  214. Parameter ab is the arc begin angle and ae is arc end angle (in
  215. radians). Angles are measured counter-clockwise from the positive x
  216. axis. X and y are the center point. R is the radius.
  217.  
  218. -----------------------------------------------------------------------
  219. call ellipse(x,y,a,b,theta)        !  draw an ellipse in problem space
  220.  
  221. Draw a a 64 line segment ellipse centered at x,y: the semi-major axis
  222. is aligned delta radians CCW from the positive x axis.
  223.  
  224. a - semi-major axis;  b - semi-minor axis
  225.  
  226. Uses a formulation which eliminates the use of trigonometric
  227. trancendental functions inside the loop.
  228.  
  229. -----------------------------------------------------------------------
  230. call cursor(irow,icol)        !  position the cursor
  231.  
  232. Set A/N cursor position at (row,column). In FORTRAN, a write always
  233. starts in column one. Cursor can be used to set the row.
  234.  
  235. -----------------------------------------------------------------------
  236. call putstr(x,y,string)        !  output a string at (x,y) on screen
  237. integer x,y
  238. character string*(*)
  239.  
  240. -----------------------------------------------------------------------
  241. call pause('message')        !  put pause message at bottom of the screen
  242. call error('message')        !  put error message at bottom of the screen
  243. call warn('message')        !  put warning message at bottom of the screen
  244. call info('message')        !  put advisory message at bottom of the screen
  245.  
  246. ---------------------------------------------------------------------
  247. LEVEL THREE NOTES
  248. ---------------------------------------------------------------------
  249. GRAFX level three contains FORTRAN 77 callable primitive graphics
  250. functions in assembler for CGA HI-RES MONO mode. The routines ASET,
  251. GSET, ACLS, GCLS are called directly from FORTRAN applications. The
  252. routines PSET, PLINE, and PCURSO can be call directly, but are best
  253. used by calling the companion FORTRAN subroutines POINT, LINE, and
  254. CURSOR.
  255.  
  256. ---------------------------------------------------------------------
  257. call gset                    !  set graphic; mode = 6
  258. call gcls                    !  clear graphic display
  259. call aset                    !  set alpha; mode = 2
  260. call acls                    !  clear alpha display
  261.  
  262. ---------------------------------------------------------------------
  263. integer*2 row,column
  264. call pset(row,column)        !  turn on a pixel at screen coordinate
  265.  
  266. Directly accesses the PCs display memory and uses a variety of rather
  267. obscure techniques (e.g. synthetic multiplication) to compute the
  268. address of the required byte access, form the needed bit mask, and turn
  269. on the pixel as fast and efficiently as possible.
  270.  
  271. ---------------------------------------------------------------------
  272. integer*2 row,column
  273. call pclr(row,column)        !  turn off a pixel at screen coordinate
  274.  
  275. Turn off the pixel.
  276.  
  277. ---------------------------------------------------------------------
  278. integer*2 ptst,row,column,k
  279. k=ptst(row,column)        !  test a pixel at screen coordinate
  280.  
  281. Test the PCs display memory to see if a pixel is currently on. A none
  282. zero value indicates that the pixel is on.
  283.  
  284. ---------------------------------------------------------------------
  285. integer*2 y1,x1,y2,x2        !  coordinate p1 to p2
  286. call pline(y1,x1,y2,x2)        !  draw a line from screen coordinate p1 to p2
  287.  
  288. Implements Jack Bresenham's Fast Line Algorithm, which uses only
  289. integer addition and subtraction operations, in 8086 assembler. This
  290. results in the fastest possible line drawing speeds. Line color is
  291. selected by calling COLOR or PCOLOR. The default color is white or
  292. "on".
  293.  
  294. ---------------------------------------------------------------------
  295. integer*2 color
  296. call pcolor(color)
  297.  
  298. Sets line color 0 = black; otherwise white. This affects all level two
  299. routines except point and can be used to erase lines and shapes.
  300.  
  301. ---------------------------------------------------------------------
  302. FORTRAN 77 callable 16 bit logical and shift functions
  303. --------------------------------------------------------------------
  304. logical and function            k=land(i,j)
  305. logical or function             k=lor(i,j)
  306. logical exclusive or function        k=leor(i,j)
  307. logical not function             j=lnot(i)
  308. logical right shift function        j=lshr(i,nbits)
  309. logical left shift function        j=lshl(i,nbits)
  310.  
  311. Declare these functions integer*2 in calling program. I, J, K, and
  312. NBITS must also be integer*2
  313.  
  314. integer*2 land,lor,leor,lnot,lshr,lshl
  315. integer*2 i,j,k,nbits
  316.  
  317. ---------------------------------------------------------------------
  318. MISCELLANEOUS ROUTINE NOTES
  319. ---------------------------------------------------------------------
  320. character ch
  321. integer*2 ich
  322.  
  323. ich=ichar(ch)
  324. call putch(ich)            !  put a character at current cursor position
  325.  
  326. ---------------------------------------------------------------------
  327. integer*2 row,column
  328.  
  329. call pcurso(row,column)        !  position the cursor at row, column
  330.  
  331. ---------------------------------------------------------------------
  332. call beep                    !  beep the speaker
  333. call reply                !  wait until a key is pressed
  334. call lclr                    !  clear to end of current line
  335.  
  336. ---------------------------------------------------------------------
  337. integer*2 ich
  338.  
  339. call ckey(ich)                !  check to see if a key has been pressed
  340.  
  341. If a key has been pressed and a character is in the buffer, return with
  342. ich = ASCII code, otherwise ich = 0.
  343. ---------------------------------------------------------------------
  344. call fdate(id,im,iy)        !  day month year
  345. integer id,im,iy
  346.  
  347. call fsecs(seconds)            !  return time in seconds & fraction
  348.  
  349. call delay(delt)            !  delay for "delt" seconds and return
  350.  
  351. call ftime(hh,mm,ss,fss)        !  time in hours, minutes, seconds
  352. integer hh,mm,ss,fss        !  and hundreths of seconds
  353.  
  354. integer*2 dd,mm,yy
  355. call adate(dd,mm,yy)        !  assembly routine to get date
  356.  
  357. integer counts
  358. call atime(counts)            !  assembly routine to get time
  359.  
  360. COUNTS can be used to seed the supplied random number generator RAND to
  361. obtain a different list of pseudo-random numbers each time the
  362. application is used. Time of day in seconds is equal to counts/18.2.
  363.  
  364. ---------------------------------------------------------------------
  365. subroutine clip(x1,y1,x2,y2,nc)
  366.  
  367. Clip a vector to problem space. The vector is from (x1,y1) to (x2,y2).
  368. variable "nc" returns -1 if unplottable or the number of clips
  369. performed (0-4). CLIP is supplied for optional use by the programmer
  370. in applications where vectors may extend beyond the problem space window.
  371.  
  372. ---------------------------------------------------------------------
  373. call peek(iaddr,ival)            !  get a two byte quantity fm iaddr
  374.  
  375. integer*4 iaddr                !  physical address
  376. integer*2 ival
  377.  
  378. ---------------------------------------------------------------------
  379. call poke(iaddr, ival)            !  put a two byte quantity at iaddr
  380.  
  381. integer*4 iaddr
  382. integer*2 ival
  383.  
  384. ------------------------------------------------------------
  385. function rnd(irk)            !  pseudo-random number generator
  386. function rand(irk)            !  pseudo-random number generator
  387.  
  388. Prime modulus linear congruential generator (Lehmer generator) of the
  389. form f(z)=a*z mod m; where a ~=sqrt(m).  This version uses a=7**5,
  390. m=2**31-1. Seed with an integer variable "irk" containing 1.  Meets the
  391. minimal Lehmer standard!  See Park & Miller; "Random Number Generators:
  392. Good Ones are Hard to Find"; Communications of the ACM; V31 N10 (1988).
  393.  
  394. WARNING: The function name RND() is used by Lahey F77L FORTRAN as a
  395. non-standard intrinsic. When using RND with F77L declare RND external
  396. to avoid using the non-standard intrinsic RND.
  397.  
  398.     external rnd
  399.  
  400. The function RAND is included to provide the exact same service without
  401. such a conflict.  If a different sequence of random numbers is desired
  402. each time you run a program use the atime routine to obtain a seed
  403. based on the the time of day counter.
  404.  
  405. -----------------------------------------------------------------------
  406. Portability
  407. -----------------------------------------------------------------------
  408. GRAFX was designed to be portable in three dimensions: one, portable to
  409. other FORTRAN compilers; two, portable to other operating systems; and
  410. three, portable to other computers and graphics hardware. 
  411.  
  412. GRAFX is written in US ANSI FORTRAN 77. The only non-standard feature
  413. used is trailing comments, which will be a FORTRAN 8X standard. No
  414. vendor specific non-standard features are used. Any FORTRAN extensions
  415. required are implemented as primitive subroutines or functions (such as
  416. bit manipulation) as part of the GRAFX library.
  417.  
  418. Only a minimal set of DOS/BIOS services are used. Access to these
  419. system services is through calls to primitive assembly language
  420. routines which isolate specific functions.
  421.  
  422. All GRAFX graphic operations are reduced to a few primitive functions,
  423. which are common to all graphic displays.Rather than use a lot of
  424. display hardware dependent shape generation algorithms, all shapes are
  425. reduced to vector operations. The graphic display hardware specific
  426. features are isolated in one small (about 1 KB object code) set of 8086
  427. assembly language routines.
  428.  
  429. Because portability is "designed in" applications which use GRAFX can
  430. be moved to newer PC technology, mini/mainframe, or even to a super
  431. computer environment easily. In fact, the design of GRAFX reflects
  432. years of experience in designing, building and maintaining applications
  433. which must run in IBM 30XX, DEC VAX, and INTEL 8086 environments
  434. inclusively.
  435.  
  436. ---------------------------------------------------------------------
  437. Compatibility
  438. ---------------------------------------------------------------------
  439. The current distribution diskette contains libraries for Lahey FORTRAN
  440. F77L V3.0 and Lahey Personal FORTRAN 77 (LP77).  The libraries were
  441. created using the Lahey library manager (LM), supplied with F77L and
  442. LP77.  You can use the Lahey Library Manager (LM) add to the GRAFX
  443. library or add the GRAFX routines to your current libraries.
  444.  
  445. The primitives are compatible with MS DOS Version 3.10 and later and
  446. CGA video mode 6.
  447.  
  448. Call for information on other versions and/or source code availability.
  449.  
  450. ---------------------------------------------------------------------
  451. Suggestions for additions and improvements are greatly appreciated.
  452. Enhancements in final testing include a scalable vector (soft)
  453. character set which can be positioned to the nearest pixel and
  454. additional top level routines. Color support for 640 X 480 VGA mode is
  455. under preparation.  Our priorities for introduction are a direct
  456. reflection of your requests.
  457.  
  458. Additional library routines are available which support geographic
  459. displays, date conversions, numerical analysis, numerical simulation,
  460. orbital mechanics, radar systems analysis, and other scientific and
  461. engineering applications.  For further details and custom requirements,
  462. contact:
  463.  
  464.     Jim Farrell
  465.     Ridge Technology 
  466.     1867 Park Road, N.W. 
  467.     Washington, D.C. 20010 
  468.     (202) 232-1441 
  469. .+
  470.