Shareware Overload/ShartewareOverload.cdr/progm/pcgraphc.zip/GFUNCT.TXT

Text File | 1989-01-14 | 26KB | 738 lines

Header Files

There are two header files used by these programs.  They are
gr_lib.h and graph.h .  The gr_lib.h file is used to compile the
code for the graphics routines and the labels.  The file graph.h
is for use with user programs and defines the screen modes which
are supported.  It also contains an external declaration for two
variables: X_mm and Y_mm.  These are the screen sizes of your
particular system.  If the scaling routines are to work properly,
these must be set to the particular hardware in use.  For
example:

extern double X_mm = 220.0, Y_mm = 160.0;    /* screen size in mm */

sets up the routines for a CRT with a graphics area 220 mm wide
and 160 mm tall.

To find the size of the graphics CRT on your system, run lb_demo
and measure the size of the frame drawn by this program.  Edit
the graph.h file definitions for X_mm and Y_mm and substitute
these numbers for the present values.



Differences From the Hewlett-Packard Series 200/300 Workstation
BASIC

One of the major differences is the ability of the HP BASIC to
default non-existant arguments for functions.  For example,
locate () requires all arguments to be present.  The BASIC
function LOCATE can have no arguments: it will draw a full screen
cursor on the screen for you to digitize the missing coordinates.
To do so in C would require access to the argument count when the
function is called.

While it is not impossible to access the argument count in a
portable fashion, it is difficult to do so.  The portable
argument count mechanism is aimed at functions which behave like
printf (), and is not targeted to functions whose behavior
changes with different argument counts.  It is also difficult to
convince the compilers to accept function prototyping and yet
permit varying argument counts without generating warnings.

For these reasons, all functions must have a complete list of
arguments, except for labelf () which functions perfectly with
the portable argument count mechanisms.  For the remaining
functions which require all arguments, an optional argument may
be set to zero.  In this case, the default value is used.
Functions which accept default values state this in the parameter
list for the function.



Supported Graphics Modes

The following graphics modes are supported:

CGA_320x200    1    /* BIOS CGA 320x200, 4 color */
CGA_640x200    2    /* BIOS CGA 640x200 BW */
ATT_640x400    3    /* AT&T 640x400 BW, tiny type */
EGA_320x200    4    /* IBM EGA low-res 320x200, 16 color */
EGA_640x200    5    /* IBM EGA med-res 640x200, 16 color */
EGA_640x350    6    /* IBM EGA high-res 640x350, 16 color */
VGA_640x480    7    /* IBM VGA high-res 640x480, 16 color */
VGA_320x200    8    /* IBM VGA lo-res 320x200, 256 color */

No provisions were made for the Hercules graphics controllers
because no information was available on their programming when
this code was written.  Inclusion of these modes simply requires
linking in the support libraries and setting a flag in the
g_init () routine which would be read by the putdot () function
in graphx.c This function would then alternatively use either
the BIOS interface or the Hercules library when drawing.



Function Summary


clip ( Xmin, Xmax, Ymin, Ymax )

Parameter    Minimum value    Maximum value    Default   Units

Xmin        -1.7E+308    1.7E+308    none      User
Xmax        -1.7E+308    1.7E+308    none      User
Ymin        -1.7E+308    1.7E+308    none      User
Ymax        -1.7E+308    1.7E+308    none      User

The function clip () defines a soft-clipping window within which
to plot.  The lower left corner of the window is defined by
( Xmin, Ymin ), and the upper right corner of the window is
defined by ( Xmax, Ymax ).  The default soft clip window is set
by the locate () function.  Calling locate () resets the
soft clip window to the locate area.

Note that this function is slightly different than the function
as implimented in HP workstation BASIC.  First, you must supply
arguments to the clip () function:  You can not omit the values
and digitize the corners of the soft clip window.
_________________________________________________________________


clip_off ()

This function turns off the soft clipping limits and sets the
clipping window to the hard clip window ( either set by default
or the limit () function ).
_________________________________________________________________



clip_on ()

This function turns on the soft clipping limits if they were
turned off by clip_off ().
_________________________________________________________________



csize ( size, aspect_ratio, tilt_angle )

Parameter    Minimum    value    Maximum value    Default        Units

size         1.7E-308    1.7E+308    5        GDU's
aspect_ratio     1.7E-308    1.7E+308    0.6
tilt_angle    -1.7E+308    1.7E+308    none        current
                                angle units

Default values for any argument are invoked by a zero (0) for
that argument.

This function controls the size, aspect ratio, and tilt angle of
the characters drawn by labelf ().  At initialization, the
character size is set to 5 GDU's, at an aspect ratio of 0.6.
There is no tilt.  Note that, although the angle ranges cover the
full range of type double, there is no point in using angles
which exceed either +/- 360 degrees or +/- 2 * pi radians.

A floating point math error will occur for any angle which resolves
to n * 90 degrees or n * pi/2 radians for any odd values of n.
_________________________________________________________________



deg ();

This function sets the current angle unit to degrees.

Affects: ldir (), pdir (), pivot ().
_________________________________________________________________



draw ( X, Y )

Parameter    Minimum value    Maximum value    Default   Units

X        -1.7E-308    1.7E+308    none      current
Y        -1.7E-308    1.7E+308    none      current


This function draws a line from the current position to (X, Y)
using the current pen color and line type.  If the pen is up,
this function will lower the pen prior to drawing the line.  The
pen will remain down after the line is drawn.
_________________________________________________________________



frame ()

Draw a frame around the current clipping window using the current
pen color and line type.  After the frame is complete, the pen is
positioned to the lower left corner of the frame and the pen is
raised.
_________________________________________________________________



gclear ()

gclear () erases the data within the current clipping window.
The areas outside of this boundary are not affected.  Executing
the clip_off () function will cause gclear () to clear the
hard clip window.

Note:  This particular function is very (!!) slow on account of
using the BIOS routines to place the pixels.  This allows machine
independence without significant software complexity and is very
portable.  If it is not important to clear only the clip window,
execution of g_init () will clear the entire screen, but all
windowing, scaling, pivoting, plotting directions, labeling
information, and current position are lost.
_________________________________________________________________



g_init ()

This function initializes the graphics function and sets the
screen mode to graphics.  This function must be called prior to
issuing any call to any function in this library.  g_init ()
sets the following parameters when called:

pen        1
line type    1
csize        4 GDU's
pdir        0 degrees
mode        degrees
ldir        0 degrees
lorg        1
hard clip    full screen
soft clip    full screen
pivot        0 degrees at origin (0,0)
_________________________________________________________________



graphics_off ()

This function will exit from the graphics screen and return to
the alpha screen.  Unfortunately, unlike the Hewlett-Packard
series 200/300 computers, the contents of the screen are erased
by this transition.
_________________________________________________________________



idraw ( Xinc, Yinc )

Parameter    Minimum value    Maximum value    Default   Units

Xinc        -1.7E-308    1.7E+308    none      current
Yinc        -1.7E-308    1.7E+308    none      current


This function draws a line from the current position (Xp, Yp) to
position (Xp + Xinc, Yp + Yinc) using the current pen color and line
type.  If the pen is up, this function will lower the pen prior
to drawing the line.  The position (Xp, Yp) is then updated to
the new pen position.  When the line is finished, the pen will
remain down.
_________________________________________________________________



imove ( Xinc, Yinc )

Parameter    Minimum value    Maximum value    Default   Units

Xinc        -1.7E-308    1.7E+308    none      current
Yinc        -1.7E-308    1.7E+308    none      current

Function imove () incrementally moves from the current position
(Xp, Yp) to position (Xp + Xinc, Yp + Yinc).  If the pen was
down, it is raised before moving.  After moving, (Xp, Yp) will
be updated to the new pen position.
_________________________________________________________________



iplot ( Xinc, Yinc, penc )

Parameter    Minimum value    Maximum value    Default   Units

Xinc        -1.7E-308    1.7E+308    none      current
Yinc        -1.7E-308    1.7E+308    none      current
penc        -32768        32767        none      N/A

iplot () draws incrementally from the last position (Xp, Yp) to
position (Xp + Xinc, Yp + Yinc).  After moving the position
(Xp, Yp) is updated to the new pen location.  The pen control
parameter (penc) is interpreted as follows:

    penc value    Action

    + Even        move and then raise pen
    - Even        raise pen and then move
    + Odd        move and then drop pen
    - Odd        drop pen and then move

iplot () is affected by pivot () and pdir ().
_________________________________________________________________



labelf ( "format string" [, optional argument list] );

labelf () functions exactly as printf ().  Imbedded carriage
returns result in the line starting 1 line below the present
line.  Labels are positioned by the functions lorg () and ldir
() and the size is governed by csize ().  Care must be used when
imbedding control characters.  In general, no non-printing
characters are counted when label positions are calculated, and
imbedded backspace characters (\b) are ignored.  A label may be
drawn at any postion and angle using any size, aspect ratio,
and origin using any pen color and line type.

Note that only line type # 1 will result in smooth and continuous
characters.

See also lorg (), ldir (), and csize ().

labelf () is not affected by pivot () and pdir ()
transformations.
_________________________________________________________________



ldir ( angle )

ldir () sets the angle at which to draw labels.  The
specification of the angle may be in degrees or radians as set
by the most recent deg () or rad () function call.  Positive
angle are measured counter-clockwise from the positive x-axis.
_________________________________________________________________



limit ( Xmin, Xmax, Ymin, Ymax )

Parameter    Minimum value    Maximum value    Default       units

Xmin        -1.7E+308    1.7E+308    none       mm's
Xmax        -1.7E+308    1.7E+308    none       mm's
Ymin        -1.7E+308    1.7E+308    none       mm's
Ymax        -1.7E+308    1.7E+308    none       mm's

The limit () function is used to re-define the hard clip
boundaries of the screen.  limit () clears any previous pivot ()
data and returns the pivot angle to 0 and the pivot point to the
lower left corner (origin).  These are the absolute plotting
limits, and the pen can not be made to move outside of these
limits under program control.

limit () does not change scaling parameters to reflect the
changed drawing area.  One should set the hard clip limits using
limit () and then define the scaling are (using locate () ) and
then scale the are using either mscale (), show (), or scale ().
_________________________________________________________________



line_type ( type_no, repeat )

Parameter    Minimum value    Maximum value    Default       Units

type_no        1        10        none       N/A
repeat        0        1.7E+308    5       GDU's

The default value for repeat length is invoked by a value of zero
for this parameter.

The line_type () function is used to select lines for
differentiating between items in a drawing or graph.  There are
10 line types described below.  Although the original HP programs
restricted line pattern repeats to integer multiples of 5 GDU's,
no such restriction is present in this program.

Line type    description

1        Solid
2        Dot only at endpoint
3        Lightly dotted line
4        Densely dotted line
5        Broken line of one dash
6        Broken line of one dash and one dot
7        Broken line of one long dash and one short dash
8        Broken line of one dash and two dots
9        Solid line with 1 GDU ticks
10        Solid line with 2 GDU ticks

For line types 9 and 10, the ticks are drawn vertically for lines
within 45 degrees of the x-axis and horizontally for lines drawn
above 45 degrees from the x-axis.  Because the IBM PC and PC
compatibles do not generally have square pixels (i.e. pixel
aspect ratio and physical screen aspect ratio are not identical),
the apparent angle at which the switch between vertical and
horizontal ticks will not be 45 degrees.  This occurs because the
pixel drawing algorithm is based in pixels, and the calculation
of the starting and ending points of lines is scaled so that the
visual information is intuitively correct (i.e., a 45 deg. angle
appears as a 45 degree angle on the screen).  For example, assume
a PC has a 1.38:1 physical aspect ratio.  In the 640 x 200
drawing mode, the aspect ratio of the pixels is 3.20:1.  Thus,
the horizontal pixels are 2.33 times narrower than the vertical
pixels are tall.  The arctangent of 2.33 is 66.77 degrees.  A
line at 66.77 degrees (physically) will thus be at the pixel
ratio of 1:1 or 45 degrees as far as the drawing algorithm is
concerned.  Lines above this angle will have horizontal ticks
and lines below this angle will have vertical ticks.

Line patterns are continuous from one line to the next.  THus, if
a move occurs after a particular line is drawn, the next line will
start at the point in the pattern where the last line left
stopped.  To re-start the line drawing pattern, simply call the
line_type () function again with the same parameters as used in the
call which set the current pattern.

_________________________________________________________________



locate ( Xmin, Xmax, Ymin, Ymax )

Parameter    Minimum value    Maximum value    Default       Units

Xmin        -1.7E+308    1.7E+308    none       GDU
Xmax        -1.7E+308    1.7E+308    none       GDU
Ymin        -1.7E+308    1.7E+308    none       GDU
Ymax        -1.7E+308    1.7E+308    none       GDU

locate () is used to define the area to be scaled by scale (),
mscale (), or show ().  The parameters for the locate ()
function are always interpreted as GDU's from the lower left
corner of the hard clip area (set by limit () ).  The locate ()
function also defines the soft clip limits to be the same as the
locate window.
_________________________________________________________________



lorg ( origin_number )

Parameter    Minimum value    Maximum value    Default       Units

origin_number    1        9        none


Select an origin for use with labelf ().  The following
illustrates the origin locations:

 3                  6                 9
   +-----------------+-----------------+
   |                 |                 |
   |                 |                 |
   |  b              |                 |
   |  b              |                 |
   |  b            5 |               8 |
 2 +  b bbbb       oo+oo     x        x+
   |  b     b    o   |   o    x      x |
   |  b      b  o    |    o     x  x   |
   |  b     b    o   |   o     x    x  |
   |  bbbbb        oo|oo     x        x|
   |                 |                 |
   +-----------------+-----------------+
  1                 4                 7


In summary, origins 1, 2, or 3 deliver left justified text.
Origins 4, 5, or 6 center the text, and origins 8, 9, and 10
offer right justified text.  Justification is performed relative
to the current pen position.
_________________________________________________________________



move ( X, Y )

Parameter    Minimum value    Maximum value    Default      Units

X        1.7E+308    1.7E+308    none      UDU's
Y        1.7E+308    1.7E+308    none      UDU's

The move () function raises the pen and moves to the specified
(X, Y) position.  The pen remains up after a move.

move () is affected by pivot () transformations.
_________________________________________________________________



mscale ( Xmin, Ymin )

Parameter    Minimum value    Maximum value    Default       Units

Xmin        -1.7E+308    1.7E+308    none       mm
Ymin        -1.7E+308    1.7E+308    none       mm

Scale the locate area in millimeters.  The coordinate pair (Xmin, Ymin)
defines the lower left corner of the locate area.

For this function to work properly, it is necessary for the user
to provide the correct graphics screen size in the graph.h header
file.
_________________________________________________________________



pen ( pen_number )

Parameter    Minimum value    Maximum value    Default       Units

pen_number    -32768        32767        none       none


This function is used to select the color of the pen for
plotting.  The default pen after g_init () is pen # 1.  On the
Hewlett-Packard systems, pen # 1 is white at power up.  On the
IBM compatible computers, it is not.  Usually, the highest number
pen is white.  Pen numbers are limited to those defined for a
particular mode.  Pen numbers in excess of the maximum defined
for a particular graphics mode are usually drawn in background
color or not drawn at all.

A negative pen value overwrites in background color (i.e., a
line drawn with pen # 1 and overwritten with pen # -1 will be
erased from the screen).  Because of limitations in the PC
graphics hardware, any negative pen number erases all pixel
colors, not just the pixel colors for that pen.  This is because
the PC graphics adapters do not have a bitwise AND function built
in.  Instead, they have a bitwise XOR function.  This will erase
only pixels of the same color as are being drawn, but if no
pixel is present in that color, it will draw one.  This behaviour
is highly undesireable, and for that reason, a negative pen
number will erase all line colors by drawing in background color.
_________________________________________________________________



penup ()

penup () lifts the pen from the plotting surface.  On the CRT,
this stops line drawing.  The pen will remain up until pen
control is changed by another statement.
_________________________________________________________________



pdir ( angle )

Parameter    Minimum value    Maximum value    Default       Units

angle        -1.7E+308    1.7E+308    none       degrees
                                                           or
                                                           radians

pdir () specifies the angle at which the axes are rotated when
drawing with incrimental or relative plotting functions iplot (),
idraw (), imove (), rplot (), rdraw (), rmove ().  Labels written
with labelf () are not affected.  The angular units may be
specified either in degrees or radians.  At g_init (), the units
is degrees, but this may be changed at any time after g_init ()
by using either deg () to set degrees, or rad () to set radians.

pdir () is affected by pivot ().
_________________________________________________________________



pivot ( angle )

Parameter    Minimum value    Maximum value    Default       Units

angle        -1.7E+308    1.7E+308    none       degrees
                                                           or
                                                           radians

The pivot () function is used to rotate the coordinate axes by
angle around the current (X, Y) location.  This transformation
applies to all drawn lines except axes (), grid (), and label ().
The current units for angle are used.

If pivot () is invoked a second time, it establishes a new pivot
point using the original coordinate system. It does not pivot
about the current position in the current coordinate system (which
is pivoted).  This means that the pivoting can be removed at any
point on the plot by invoking pivot ( 0 ).
_________________________________________________________________



plot ( X, Y, penc )

Parameter    Minimum value    Maximum value    Default       Units

X        -1.7E-308    1.7E+308    none      current
Y        -1.7E-308    1.7E+308    none      current
penc        -32768        32767        none      N/A

plot () draws from the last position (X, Y) to the specified
position (X, Y).  The type of line drawn is taken from the
current line type.  The pen control parameter (penc) is
interpreted as follows:

    penc value    Action

    + Even        move and then raise pen
    - Even        raise pen and then move
    + Odd        move and then drop pen
    - Odd        drop pen and then move

plot () is affected by pivot ().
_________________________________________________________________



rad ()

This function set the current angle units to radians.

Affects: ldir (), pdir (), pivot ().
_________________________________________________________________



ratio ()

The ratio function returns the aspect ratio of the hard clip area.
This is normally the full graphics screen unless the size has
been changed by using limit ().  Because the pixels in IBM PC
compatibles are not square ( that is, the number of pixels /cm in
the x-direction is not the same as the number of pixels /cm in
the y-direction), the number returned by this function may appear
to be non-sensical.  It is correct, but it reflects the aspect
ratio if the pixels were square.  This is one of several
limitations of the program which are hardware related.
_________________________________________________________________



rdraw ( Xr, Yr )

Parameter    Minimum value    Maximum value    Default       Units

Xr        -1.7E+308    1.7E+308    none      current
Yr        -1.7E+308    1.7E+308    none      current

The rdraw () function draws using the last absolute position
specified as the reference position (Xref, Yref).  A reference position is
the last position set by one of the following motion or plotting
functions: move (), draw (), plot (), imove (), idraw (), iplot
(), label (), axes (), frame (), or grid () .  A line is drawn from
the last position (X, Y) to the position (Xref + Xr, Yref + Yr).
The type of line drawn is taken from the current line type.

rdraw () is affected by pivot () and pdir ().
_________________________________________________________________



rmove ( X, Y )

Parameter    Minimum value    Maximum value    Default       Units

Xr        -1.7E+308    1.7E+308    none      current
Yr        -1.7E+308    1.7E+308    none      current

The rmove () function moves using the last absolute position
specified as the reference position (Xref, Yref).  A reference position is
the last position set by one of the following motion or plotting
functions: move (), draw (), plot (), imove (), idraw (), iplot
(), label (), axes (), frame (), grid () .  The pen is moved from
the last position (X, Y) to the position (Xref + Xr, Yref + Yr).

rmove () is affected by pivot () and pdir ().
_________________________________________________________________



rplot ( X, Y, penc )

Parameter    Minimum value    Maximum value    Default       Units

Xr        -1.7E-308    1.7E+308    none      current
Yr        -1.7E-308    1.7E+308    none      current
penc        -32768        32767        none      N/A

The rplot () function draws using the last absolute position
specified as the reference position (Xref, Yref).  A reference position is
the last position set by one of the following motion or plotting
functions: move (), draw (), plot (), imove (), idraw (), iplot
(), label (), axes (), frame (), grid () .  A line is drawn from
the last position (X, Y) to the position (Xref + Xr, Yref + Yr).
The type of line drawn is taken from the current line type.  The
pen control parameter (penc) is interpreted as follows:

    penc value    Action

    + Even        move and then raise pen
    - Even        raise pen and then move
    + Odd        move and then drop pen
    - Odd        drop pen and then move

rplot () is affected by pivot () and pdir ().
_________________________________________________________________



show ( Xmin, Xmax, Ymin, Ymax )

Parameter    Minimum value    Maximum value    Default       Units

Xmin        -1.7E+308    1.7E+308    none       user
Xmax        -1.7E+308    1.7E+308    none       user
Ymin        -1.7E+308    1.7E+308    none       user
Ymax        -1.7E+308    1.7E+308    none       user

The show () function scales the locate area such that a
physical representation of 1 unit along either the X- or Y-axis
has the same physical size (i.e., square objects appear square ).
_________________________________________________________________



setgu ()

This function changes the display units of the drawing from user
defined units (UDU's) to graphics display units (GDU's).
_________________________________________________________________



setuu ()

This function changes the display units of the drawing from
graphics display units (GDU's) to user defined units (UDU's).  The
user units must have been previously defined using either scale (),
show (), or mscale ().
_________________________________________________________________



scale ( Xmin, Xmax, Ymin, Ymax )

Parameter    Minimum value    Maximum value    Default       Units

Xmin        -1.7E+308    1.7E+308    none       user
Xmax        -1.7E+308    1.7E+308    none       user
Ymin        -1.7E+308    1.7E+308    none       user
Ymax        -1.7E+308    1.7E+308    none       user

The scale () function defines the minimum and maximum user units
each axis of the area specified by locate ().
_________________________________________________________________