home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Overload
/
ShartewareOverload.cdr
/
progm
/
grafx.zip
/
NOTES.DOC
< prev
next >
Wrap
Text File
|
1989-03-21
|
20KB
|
470 lines
.-
GRAFX PROGRAMMER NOTES
(C) Copyright 1988, 1989 by Jim Farrell All Rights Reserved.
GRAFX is a FORTRAN extension library of over 50 routines which gives
the FORTRAN user access to the PC's graphic video display and a
selection of DOS and BIOS services. GRAFX can save you time and money
in solving problems and communicating results. Several complete
examples are included.
The following notes provide information on how to call the GRAFX
library subroutines and functions. Most usage and conventions can be
determined from studying the example programs included on the the
distribution diskette.
-----------------------------------------------------------------------
TOP LEVEL ROUTINE NOTES
-----------------------------------------------------------------------
The following routine uses the lower level routines to produce a x-y
plot display.
-----------------------------------------------------------------------
call xyplt(x,y,n,iv,ip) ! produce x-y plots
real x(*),y(*)
A quick look x-y plot routine (scatter plot). Up to three plots may be
displayed on the screen by calling with IV=1..3. If 1 > IV > 3 then a
full screen plot is displayed. IP determines the display type IP=0,
plot a point; IP=1, plot a histogram like line from y=minimum to y(i);
IP=2, plot a histogram like line from y=0 to y(i); IP=3, plot from
(0,0) to (x,y); IP=4, plot a connected line. A WARNING is issued if
the data range is inappropriate for the selected IP.
-----------------------------------------------------------------------
The following routine uses the lower level routines to display equally
spaced samples (e.g. time series) display.
-----------------------------------------------------------------------
call tplot(xmn,xmx,y,n,iv,ip) ! produce y=f(t) plots
real y(*)
A quick look y=f(t) plot routine for equally spaced data. Up to three
plots may be displayed on the screen by calling with IV=1..3; Any other
value of IV yields a full screen plot. IP determines the display type
IP=0, plot a point; IP=1, plot a histogram like line from y=minimum to
y(i); IP=2, plot a histogram like line from y=0 to y(i); IP=3, plot
from (0,0) to (x,y); IP=4, plot a connected line. A WARNING is issued
if the data range is inappropriate for the selected IP. See example
program for a demonstration of line drawing types.
-----------------------------------------------------------------------
The following routine uses the lower level routines to display
intrinsic or external functions.
-----------------------------------------------------------------------
call fcnplt(xmn,xmx,fcn,n,iv,ip) ! produce y=fcn(x)
external fcn
or
intrinsic fcn
A quick look y=fcn(x) plot routine for n points over a range of x. Up
to three plots may be displayed on the screen by calling with IV=1..3;
Any other value of IV yields a full screen plot. IP determines the
display type IP=0, plot a point; IP=1, plot a histogram like line from
y=minimum to y(i); IP=2, plot a histogram like line from y=0 to y(i);
IP=3, plot from (0,0) to (x,y); IP=4, plot a connected line. A WARNING
is issued if the data range is inappropriate for the selected IP. See
example program for a demonstration of line drawing types.
-----------------------------------------------------------------------
The following routine uses the lower level routines to produce multiple
plot display.
-----------------------------------------------------------------------
subroutine mulplt0(xmn,ymn,xmx,ymx)
...initialize limits for multiple x-y plots
A WARNING is issued if the data range is inappropriate for the selected
IP.
subroutine mulplt(x,y,n,ip) ! produce multiple x-y plots
real x(*),y(*)
A multiple x-y plot routine. IP determines the display type IP=0, plot
a point; IP=1, plot a histogram like line from y=minimum to y(i); IP=2,
plot a histogram like line from y=0 to y(i); IP=3, plot from (0,0) to
(x,y); IP=4, plot a connected line.
-----------------------------------------------------------------------
The following routine uses the lower level routines to support
histogram display.
-----------------------------------------------------------------------
call hist(x,n) ! plot histogram
real x(*)
...routine to plot a histogram of the distribution of x. The n
occurrences of x are counted in 100 equally spaced bins. The results are
then displayed graphically.
-----------------------------------------------------------------------
MID LEVEL ROUTINE NOTES
-----------------------------------------------------------------------
GRAFX uses two include files internally:
"physcon.icl" - physical constants
"grafcom.icl" - graphic common
These are included on the distribution diskette.
Physcon.icl contains the constant PI, conversions from radians to
degrees, and earth physical constants.
Grafcom.icl contains the named COMMON /GRAFCOM/ which contains the
information to map between display space and problem space.
-----------------------------------------------------------------------
Unless otherwise noted, GRAFX assumes that the default implicit FORTRAN
conventions are:
integer*4 and real*4.
-----------------------------------------------------------------------
A BLOCK DATA module GRAFINIT initializes the problem space window to
0.0 to 1.0 in both x and y. It initializes the display space view to 0
to 639 in the x direction and 0 to 199 in the y direction. Invocation
of either WINDOW or VIEW force the loading of GRAFINIT from the
library. If you choose to use the default problem and display space
parameters without invoking either WINDOW or VIEW, the BLOCK DATA
"GRAFINIT" must be declared "external" in your program to force loading
it from the library.
-----------------------------------------------------------------------
call window(xmn,ymn,xmx,ymx) ! set problem space window
Set problem space window (left, bottom, right, top) in named COMMON
/GRAFCOM/. Origin is lower left. Next call view with display space
view. The defaults are 0.0 and 1.0 for bottom, left and top, right
respectfully.
-----------------------------------------------------------------------
call view(xmn,ymn,xmx,ymx) ! set display space view
integer xmn,ymn,xmx,ymx
Set display space window view (left, bottom, right, top) in named
COMMON /GRAFCOM/. The default is 0 to 639 for x and 0 to 199 for y.
Arguments are screen coordinates (pixels). Note that the GRAFX
convention is for the origin in the lower left corner of the screen.
ymn is the lower coordinate and ymx is the upper.
-----------------------------------------------------------------------
-----------------------------------------------------------------------
The following routines are the mid-level problem space point, line, and
shape generators. To compensate for the CGA non-linearities, shapes
are generated in problem space. The (optional) use of a 8087 numeric
coprocessor makes the conversion to display space efficient (about 20X
faster than with no 8087). Further line drawing speed is achieved
through the use of assembly language routines to perform vector to
raster conversion and direct manipulation display memory instead of
using BIOS & DOS INT services. Limit checking of points and clipping of
lines is not done. It is assumed that the user has defined appropriate
problem space limits. A clipping routine is provided in the library for
applications requiring clipping.
-----------------------------------------------------------------------
call point(xp,yp) ! light a pixel in problem space
Converts problem coordinates to display coordinates and calls pset to
light the pixel.
-----------------------------------------------------------------------
call color('BLACK')
Determine the color of lines. The default is 'WHITE' or on. In CGA
hi-res mode, there are only two possibilities. 'BLACK' turns off pixels
that are lit and can be used to erase lines.
-----------------------------------------------------------------------
call line(xp1,yp1,xp2,yp2) ! draw a problem space line (P1 ->
P2)
Converts problem coordinates to display coordinates and calls pline to
draw the line.
-----------------------------------------------------------------------
call plot(x,y,ip) ! move to problem space point P
Converts the problem coordinate to a display coordinate and moves from
the current position to x,y. If ip = 2 a line is drawn. This routine is
included to provide compatibility with CALCOMP style calls. Tests have
shown no speed advantage over subroutine line.
-----------------------------------------------------------------------
call box(x1,y1,x2,y2) ! draw a problem space box
Call line to draw the box. P1 is lower left. P2 is upper right.
-----------------------------------------------------------------------
call circle(x,y,r) ! draw a problem space circle
Uses recursive trigonometric techniques to draw a 64 line segment
circle in problem space. Only four multiplies and six additions are
inside the computational loop. X and y are the center point. R is the
radius.
-----------------------------------------------------------------------
call arc(x,y,r,ab,ae) ! draw a problem space arc
Uses a technique similar to the circle routine to draw an arc.
Parameter ab is the arc begin angle and ae is arc end angle (in
radians). Angles are measured counter-clockwise from the positive x
axis. X and y are the center point. R is the radius.
-----------------------------------------------------------------------
call ellipse(x,y,a,b,theta) ! draw an ellipse in problem space
Draw a a 64 line segment ellipse centered at x,y: the semi-major axis
is aligned delta radians CCW from the positive x axis.
a - semi-major axis; b - semi-minor axis
Uses a formulation which eliminates the use of trigonometric
trancendental functions inside the loop.
-----------------------------------------------------------------------
call cursor(irow,icol) ! position the cursor
Set A/N cursor position at (row,column). In FORTRAN, a write always
starts in column one. Cursor can be used to set the row.
-----------------------------------------------------------------------
call putstr(x,y,string) ! output a string at (x,y) on screen
integer x,y
character string*(*)
-----------------------------------------------------------------------
call pause('message') ! put pause message at bottom of the screen
call error('message') ! put error message at bottom of the screen
call warn('message') ! put warning message at bottom of the screen
call info('message') ! put advisory message at bottom of the screen
---------------------------------------------------------------------
LEVEL THREE NOTES
---------------------------------------------------------------------
GRAFX level three contains FORTRAN 77 callable primitive graphics
functions in assembler for CGA HI-RES MONO mode. The routines ASET,
GSET, ACLS, GCLS are called directly from FORTRAN applications. The
routines PSET, PLINE, and PCURSO can be call directly, but are best
used by calling the companion FORTRAN subroutines POINT, LINE, and
CURSOR.
---------------------------------------------------------------------
call gset ! set graphic; mode = 6
call gcls ! clear graphic display
call aset ! set alpha; mode = 2
call acls ! clear alpha display
---------------------------------------------------------------------
integer*2 row,column
call pset(row,column) ! turn on a pixel at screen coordinate
Directly accesses the PCs display memory and uses a variety of rather
obscure techniques (e.g. synthetic multiplication) to compute the
address of the required byte access, form the needed bit mask, and turn
on the pixel as fast and efficiently as possible.
---------------------------------------------------------------------
integer*2 row,column
call pclr(row,column) ! turn off a pixel at screen coordinate
Turn off the pixel.
---------------------------------------------------------------------
integer*2 ptst,row,column,k
k=ptst(row,column) ! test a pixel at screen coordinate
Test the PCs display memory to see if a pixel is currently on. A none
zero value indicates that the pixel is on.
---------------------------------------------------------------------
integer*2 y1,x1,y2,x2 ! coordinate p1 to p2
call pline(y1,x1,y2,x2) ! draw a line from screen coordinate p1 to p2
Implements Jack Bresenham's Fast Line Algorithm, which uses only
integer addition and subtraction operations, in 8086 assembler. This
results in the fastest possible line drawing speeds. Line color is
selected by calling COLOR or PCOLOR. The default color is white or
"on".
---------------------------------------------------------------------
integer*2 color
call pcolor(color)
Sets line color 0 = black; otherwise white. This affects all level two
routines except point and can be used to erase lines and shapes.
---------------------------------------------------------------------
FORTRAN 77 callable 16 bit logical and shift functions
--------------------------------------------------------------------
logical and function k=land(i,j)
logical or function k=lor(i,j)
logical exclusive or function k=leor(i,j)
logical not function j=lnot(i)
logical right shift function j=lshr(i,nbits)
logical left shift function j=lshl(i,nbits)
Declare these functions integer*2 in calling program. I, J, K, and
NBITS must also be integer*2
integer*2 land,lor,leor,lnot,lshr,lshl
integer*2 i,j,k,nbits
---------------------------------------------------------------------
MISCELLANEOUS ROUTINE NOTES
---------------------------------------------------------------------
character ch
integer*2 ich
ich=ichar(ch)
call putch(ich) ! put a character at current cursor position
---------------------------------------------------------------------
integer*2 row,column
call pcurso(row,column) ! position the cursor at row, column
---------------------------------------------------------------------
call beep ! beep the speaker
call reply ! wait until a key is pressed
call lclr ! clear to end of current line
---------------------------------------------------------------------
integer*2 ich
call ckey(ich) ! check to see if a key has been pressed
If a key has been pressed and a character is in the buffer, return with
ich = ASCII code, otherwise ich = 0.
---------------------------------------------------------------------
call fdate(id,im,iy) ! day month year
integer id,im,iy
call fsecs(seconds) ! return time in seconds & fraction
call delay(delt) ! delay for "delt" seconds and return
call ftime(hh,mm,ss,fss) ! time in hours, minutes, seconds
integer hh,mm,ss,fss ! and hundreths of seconds
integer*2 dd,mm,yy
call adate(dd,mm,yy) ! assembly routine to get date
integer counts
call atime(counts) ! assembly routine to get time
COUNTS can be used to seed the supplied random number generator RAND to
obtain a different list of pseudo-random numbers each time the
application is used. Time of day in seconds is equal to counts/18.2.
---------------------------------------------------------------------
subroutine clip(x1,y1,x2,y2,nc)
Clip a vector to problem space. The vector is from (x1,y1) to (x2,y2).
variable "nc" returns -1 if unplottable or the number of clips
performed (0-4). CLIP is supplied for optional use by the programmer
in applications where vectors may extend beyond the problem space window.
---------------------------------------------------------------------
call peek(iaddr,ival) ! get a two byte quantity fm iaddr
integer*4 iaddr ! physical address
integer*2 ival
---------------------------------------------------------------------
call poke(iaddr, ival) ! put a two byte quantity at iaddr
integer*4 iaddr
integer*2 ival
------------------------------------------------------------
function rnd(irk) ! pseudo-random number generator
function rand(irk) ! pseudo-random number generator
Prime modulus linear congruential generator (Lehmer generator) of the
form f(z)=a*z mod m; where a ~=sqrt(m). This version uses a=7**5,
m=2**31-1. Seed with an integer variable "irk" containing 1. Meets the
minimal Lehmer standard! See Park & Miller; "Random Number Generators:
Good Ones are Hard to Find"; Communications of the ACM; V31 N10 (1988).
WARNING: The function name RND() is used by Lahey F77L FORTRAN as a
non-standard intrinsic. When using RND with F77L declare RND external
to avoid using the non-standard intrinsic RND.
external rnd
The function RAND is included to provide the exact same service without
such a conflict. If a different sequence of random numbers is desired
each time you run a program use the atime routine to obtain a seed
based on the the time of day counter.
-----------------------------------------------------------------------
Portability
-----------------------------------------------------------------------
GRAFX was designed to be portable in three dimensions: one, portable to
other FORTRAN compilers; two, portable to other operating systems; and
three, portable to other computers and graphics hardware.
GRAFX is written in US ANSI FORTRAN 77. The only non-standard feature
used is trailing comments, which will be a FORTRAN 8X standard. No
vendor specific non-standard features are used. Any FORTRAN extensions
required are implemented as primitive subroutines or functions (such as
bit manipulation) as part of the GRAFX library.
Only a minimal set of DOS/BIOS services are used. Access to these
system services is through calls to primitive assembly language
routines which isolate specific functions.
All GRAFX graphic operations are reduced to a few primitive functions,
which are common to all graphic displays.Rather than use a lot of
display hardware dependent shape generation algorithms, all shapes are
reduced to vector operations. The graphic display hardware specific
features are isolated in one small (about 1 KB object code) set of 8086
assembly language routines.
Because portability is "designed in" applications which use GRAFX can
be moved to newer PC technology, mini/mainframe, or even to a super
computer environment easily. In fact, the design of GRAFX reflects
years of experience in designing, building and maintaining applications
which must run in IBM 30XX, DEC VAX, and INTEL 8086 environments
inclusively.
---------------------------------------------------------------------
Compatibility
---------------------------------------------------------------------
The current distribution diskette contains libraries for Lahey FORTRAN
F77L V3.0 and Lahey Personal FORTRAN 77 (LP77). The libraries were
created using the Lahey library manager (LM), supplied with F77L and
LP77. You can use the Lahey Library Manager (LM) add to the GRAFX
library or add the GRAFX routines to your current libraries.
The primitives are compatible with MS DOS Version 3.10 and later and
CGA video mode 6.
Call for information on other versions and/or source code availability.
---------------------------------------------------------------------
Suggestions for additions and improvements are greatly appreciated.
Enhancements in final testing include a scalable vector (soft)
character set which can be positioned to the nearest pixel and
additional top level routines. Color support for 640 X 480 VGA mode is
under preparation. Our priorities for introduction are a direct
reflection of your requests.
Additional library routines are available which support geographic
displays, date conversions, numerical analysis, numerical simulation,
orbital mechanics, radar systems analysis, and other scientific and
engineering applications. For further details and custom requirements,
contact:
Jim Farrell
Ridge Technology
1867 Park Road, N.W.
Washington, D.C. 20010
(202) 232-1441
.+