home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
HAM Radio 3
/
hamradioversion3.0examsandprograms1992.iso
/
packet
/
gil101
/
gilmain.doc
< prev
next >
Wrap
Text File
|
1991-04-02
|
55KB
|
1,378 lines
GIL (c)
GRAPHICS INTERCHANGE LANGUAGE
Version 1.01
A Public Domain Program
Copyright 1991 by Glenn L. Williams
Protected by Federal Copyright Law.
Permission granted for non-commercial use and distribution.
Not to be used for commercial advantage. All rights reserved.
This document contains (TBD) pages.
This is a draft copy for the beta release.
IBM(TM), AT&T(TM), Olivetti(TM), Hercules(TM),
are trademarks of those well-known companies
International Business Machines, American Telephone
and Telegraph, Olivetti of Italy, and Hercules Corp.
If other trademarks accidentally were omitted from
this list I apologize.
Disclaimer
----------
The author shall have no liability or responsibility to user or any other
person or entity with respect to any loss or damage caused or alleged to be
caused directly or indirectly through the use of this documentation or the GIL
program.
Distribution and Use of GIL
-------------------------
GIL is a copyrighted program. All rights are retained by the author. GIL is
not to be sold; nor is it to be used for commercial purposes. You may freely
distribute GIL, and you are encouraged to do so, but you may not charge for
doing so, except as permitted below. The following files should be
included in any distribution:
GIL.EXE
GIL.DOC
GILMAIN.DOC
PENG.GIL
QSL.GIL
GIL is hereby placed into the public domain, but cannot be used or sold with a
product supplied by a profit making corporation. GIL may be used by any
amateur radio operator, in amateur radio (non-profit) operating environments,
and also by any not-for-profit organization, or any government agency, as long
as product is not mixed in or sold with any for sale product costing more than
$5.00 U.S. dollars, except as noted in paragraphs below. I.e. this program may
be included in its archived (zip or arc) format or unarchive format to support
other shareware but all rights to this product are to be retained in the
public domain and the author's copyrights remain intact.
This product and its documentation in archived format may be uploaded to
public domain bulletin boards, except no license is granted hereby for any
commercial use or copyright transfer to any bill-for-service data base or
bulletin board service, including, among others, BIX(TM), PRODIGY(TM),
and COMPUSERVE(TM).
This utility is being provided free of charge for the main benefit of amateur
radio operators worldwide. In the U.S.A. amateur radio is a hobby that is
infinitely enjoyable for young and old. We "hams" cannot receive a profit
from anything we do in amateur radio, therefore, this program is freely
available and the author expects no profit from it. For this reason, this
program and the .GIL file technique are NEVER to be used as a source of income
by any individual or corporation. The copyrights are not transferable.
However, this software may be sold on floppy disk by vendors of freeware and
shareware where the floppy disks are sold for no more than $5.00 each via mail
order or at fleamarkets and hamfests.
1. Purpose
----------
The primary purpose behind GIL is to permit a convenient way for radio
amateurs to send more than just plain ASCII text messages over the packet or
RTTY radio links. Before GIL, there was no convenient way to transmit over
the radio, or via bulletin board, reasonably small "files" containing enough
information to reconstruct a good line drawing or cartoon, over the radio.
2. Starting GIL
--------------------
If you have not already done so, please make a working copy of all GIL
disk files and store away the disk on which you received GIL for safekeeping,
and use the working copy when you want to run GIL. You may write protect
the working copy because GIL will not usually write to the disk. (This applies
to version 1.01 only. In the future releases the usage of the disk may change.)
Your working disk should contain the following files:
GIL.EXE (The GIL executable program)
and several other .GIL format files for your enjoyment.
Anyone wishing to send interesting new .GIL format files to the author
would be highly appreciated. Also, new .GIL format files should be
exchanged on packet and telephone bulletin boards!!
2.1 Interactive startup
------------------------
To run GIL in interactive mode, the following command syntax is used:
Start from your DOS prompt with the command:
GIL
and when you receive the "GIL>" prompt, then type in ASCII commands that will
be further described below . As each command is typed it will be listed on the
screen, and then executed when you type the ENTER key. Just above the command
line your most recent command is listed, and just below the command line (in
some cases) are error messages. When you are done and wish to go back to DOS,
use the ".bye" command to exit.
Ultimately you may want to compose .GIL files with a text editor or word
processor and then "batch" process them through the program. Further
instructions below will describe the process in detail.
2.2 Non-interactive startup "BATCH MODE"
---------------------------- ------------
For straight ASCII file input mode, GIL accepts input from "stdin" redirection,
as follows:
GIL <[drive:][path][filename]
^
|......note this "<" character used for stdin input redirection.
At the end of the drawing process, when you are done viewing the drawing,
striking any key will clear the screen and return you to DOS.
Anyone not familiar with "stdin" redirection should consult the operation
of the DOS COMMAND.COM shell in his DOS manual.
Therefore, just for the sake of getting some idea of what GIL can do, try
the following command (VGA or EGA recommended):
GIL <OPUS.GIL
If you are an amateur radio operator, or if you have only a monochrome
Hercules Graphics Adapter, try:
GIL <QSL.GIL
If you have a TSR utility such as GRAPHICS.COM (usually supplied with your
DOS for CGA adapters), or EGAPRTSC.COM (for EGA adapters) you can also print
the screen to an IBM or EPSON dot matrix printer, for obtaining a hard copy.
That is, any TSR screen capture utility or printer utility capable of can
"grab" the screen and "live" as a TSR (Terminate and Stay Resident) utility in
your computer, can print the screen. However, at this time, the author has not
had the time and resources to test all the TSRs's out there for compatibility
with GIL. Nor is it expected at this time for GIL to cooperate with Microsoft
Windows (TM) in any way other than as a "DOS" program. But since GIL interacts
with your video card, it may or may not have a deleterious effect when
operated under programs that use screen graphics as part of a "windows" or
"shell" environment.
WARNING: GIL will interact with your screen graphics adapter. As a result
it will "trash" anything else on the screen. GIL has not been tested with
all the graphics adapters in the world, and especially not with the monochrome
versions of CGA, EGA, and VGA. The graphics routines are supported via the
Microsoft Corporation "C" library for Quick-C 2.5 (TM) and any artifacts
created by the standard library are not the fault of this author.
NOTE: No compatibility with Microsoft Windows (TM) is implied in any way.
Since GIL interacts with your video card, it may or may not have a deleterious
effect when operated under programs that use screen graphics as part of a
"windows" or "shell" environment.
2.2.1 BATCH MODE AND PIPING UNDER DOS
-------------------------------------
The GIL program accepts input from either your command line inputs that
you type in, or from "stdin" (standard input) using the redirection
symbol "<". The latter permits GIL to accept "piped" input that is
generated as the output of other programs. This piped input is very
useful in batch (.BAT) files for displaying neutral files created by
other DOS programs. (This opens up the possibility of "GIL extender"
programs that create .GIL format neutral file output from sophisticated
user interfaces!)
For example, the DOS batch file below assumes that a program MAKER.COM
creates a list of GIL commands. The list can be piped into GIL:
COPY A:OLDDATA.DAT NEWDATA.DAT
MAKER NEWDATA.DAT >GIL.OUT
TYPE GIL.OUT | GIL
With this example, MAKER operates on NEWDATA.DAT and by some magic process
generates output (to "stdout") which is redirected to the file GIL.OUT (just
so the GIL commands can be viewed later in case of a need to debug something).
GIL.OUT is then "piped into" GIL.
There is a real example of a need for this. For example, you receive via
packet radio or telephone BBS a file with a really interesting drawing. But
you want to try stretching the drawing in the Y axis direction on your
screen. The file STRETCH.BAT can take care of it WITHOUT modifying the
original .GIL data file.
type aspect.gil >temp.gil
type qsl.gil >>temp.gil
type temp.gil |gilmain
where the contents of aspect.gil is the single ASCII line:
.aspect .5
In this example, the first stdout redirection in STRETCH.BAT creates the
file TEMP.GIL. In the next line, QSL.GIL is appended to the end of the
file TEMP.GIL with the ">>" syntax for append to file. Then TEMP.GIL
is type-ed to stdout which is piped into GIL with the "|" syntax.
SOAPBOX: users not aware of the utility of "stdin", "stdout", and piping,
are missing some very useful features of DOS.
3.0 Neutral format "GIL" files
-------------------------------
Since they are ASCII files, the .GIL type neutral files can be exchanged,
sent to PBBS systems, E-Mailed, etc. to other users. Once the user has a copy
of GIL.EXE, he/she can view the "drawings" and obtain hardcopies as described
below.
It is the author's original intended purpose for amateur radio operators to
freely exchange copies of GIL.EXE and any associated .GIL type neutral files.
GIL.EXE should be exchanged via telephone modem or floppy disk ("Nike Net")
exchange.
The ASCII .GIL type neutral files are intended for exchange via packet radio
worldwide. These files carry the information for making a drawing, but being
ASCII, they contain no information of an encrypted nature which would violate
national or international regulations about exchanging encrypted information
via amateur radio. Since these files are (usually) short, they will not "hog"
precious radio bandwidth.
IMPORTANT NOTE: when using a word processor, the user should be sure to
save the final output as unformatted ASCII text output, without any of the
special formatting usually supplied by a saved word processor file. That is,
if you can view the final results with EDLIN or TYPE, then you are ready
to submit the file data to GIL.
WORDSTAR(TM), WORD(TM), WORDPERFECT(TM), FIRST PUBLISHER(TM), EXPRESS
PUBLISHER(TM) and other document processing programs usually create
other than "generic ASCII" file output. These files will cause great
confusion if used with GIL while containing embedded word processor
commands.
3.1 Use with Amateur Packet Radio and RTTY
--- --------------------------------------
Since they are ASCII files, the .GIL type neutral files can be exchanged,
sent to PBBS systems, E-Mailed, etc. to other users. Once the user has
a copy of GIL.EXE, he/she can view the "drawings" and obtain hardcopies as
described below.
As described elsewhere, GIL accepts ASCII input in a "neutral" file
format. It does NOT contain a "terminal emulator" mode in this release.
Therefore, for use with amateur radio files, the data will have to be
first downloaded and stored on disk from a radio or land line source.
Next, since most sources of data will contain other ASCII protocols and
"overhead" necessary for BBS operation, the files should be previewed first
with a text editor or word processor to clean out the portions that GIL
will treat as "garbage".
3.2 BRIEF INTRODUCTION OF THE SCREEN LAYOUT
--------------------------------------------
DEFINITION OF VIEWPORT COORDINATES
----------------------------------
Once the program start up and establishes the type of graphics controller
in use, it sets up some default colors and then issues a prompt line at the
lower left part of the screen. This will be described in more detail below.
Above the two text lines used for prompting, the rest of the screen
should be blank. Actually, this is the graphical drawing area for the
screen, called the viewport. Althought the different graphics controllers
have different pixel dimensions in X and Y on the screen, the viewport
coordinates are adjusted so YOU the user only use viewport coordinates,
with the exception of the .text command which uses 22 rows of alphanumeric
characters.
The horizontal (X) dimension of the viewport is 1000. The correct pixel values
run from 1 to 1000. However, via a technique called "clipping", all values
that exceed the size of the viewport are treated as if valid, but the only
lines and graphics that are drawn are the parts that fit inside ("are clipped
off to fit inside") the viewport.
The vertical (Y) dimension of the viewport is nominally at least 500. The
exact value used depends on the type of graphics controller and the aspect
ratio established by the .aspect command described in the Reference.
This is somewhat cut and try due to the variability in graphics adapters.
Viewport coordinates start from the top left corner of the screen
(at a point called "1,1") and run to the lower right hand corner of the
screen (at a point "1000,540") where "540" is merely the nominal height
of the viewport as described above. Therefore, all drawing commands
use viewport coordinates, NOT screen locations. (But all text commands
use screen coordinates! -- The reason for this inconsistency is described
elsewhere.)
3.3 HOW TO MAKE A DRAWING
-------------------------
If you have some idea of what you want to do, you can just enter GIL
interactively and test your commands on the screen to see what happens. Keep a
list of what they do, and later you can type them into a file with a text
editor (NOT necessarily a WORD PROCESSOR!) and then execute them in batch mode.
Another way, especially good for use with existing drawings or new very
complicated drawings, is to use lined paper or semi-transparent graph paper,
ruled off and marked for use with GIL by showing the scale in viewpoint
coordinates. For example, holding a sheet of paper in landscape orientation,
with the long axis horizontal, mark off a large box 10 units (inches, or 20
mm) across and about 6 or 7 units high. With some graph paper, such as
KEUFFEL AND ESSER(TM) graph sheets, with fine rulings (10 to the inch, every
millimeter, etc.) you can set up a reasonably tight scale with good precision.
Number the Y axis DOWN from the top and the X axis across from left to right.
Then lay this graph paper over the object to be traced, or just sketch the
object. In the case of a large scale mismatch, take your original drawing to a
photocopy center with copiers with magnify/zoom capability and make a copy that
is approximately the size you need for the graph paper.
With the drawing transferred to the graph paper, you can then compose the
commands for GIL.
APOLOGY
-------
Upon initial trial, some people may view this method of forced entry of
awkward neutral file commands into the program as being rather clumsy and
tedious. However, the resulting files are ASCII files with a very high degree
of data compression already built in. This feature, and the fact that the
data is editable by anyone on a PC with a text editor or word processor,
results in relatively small files. Such files are suitable for transmission to
amateur radio and telephone oriented bulletin board systems without the
complications of data encryption or having to purchase expensive software
graphics utilities.
3.4 VIDEO GRAPHICS CARD COMPATIBILITY
-------------------------------------
This program was written for and compiled with Microsoft Quick-C (TM) V.2.5.
For the remainder of this document, the compiler will just be called "C".
Microsoft C functions for controlling video graphics were found to excecute
faster then at least one other product on the market, and in addition, the
support of the Hercules Graphics Card was found to be a definite boon. The
program was written using the support of these functions, and therefore certain
requirements of those functions also constrain the operation of the program.
This program supports VGA, EGA, CGA, and HGC graphics controllers. In the
attempt to provide a Graphics Interchange Language that spans the breadth
of the differences between these graphics controllers, the user will have
to be aware of some compromises:
HGC (Hercules) - supports only monochrome video in 720 x 348 format
CGA (Color Graphics Adapter) - supports only 4 colors, in low
density 320 x 200 pixel format.
EGA (Enhanced Graphics Adapter) - supports only 16 colors, in
a higher density pixel format of 640 x 200.
VGA (Video Graphics Adapter) - supports either 256 colors or 16
colors, in a 640 x 480 format.
In addition, the C library used with the compiler also supports the
AT&T Olivetti variants, known as "OVGA", "OEGA", and "OCGA". It also
supports the MCGA adapter defined by IBM. Therefore support for these
adapters has been included by intent, at least. But these remain untested.
To achieve some compatibility between these graphics adapters, the usage
of color in .GIL neutral files will result in certain problems for users
restricted to CGA or HGC adapters. As a result, the program makes the following
color choices and display choices.
DISPLAY AREA
------------
All adapters are assumed to have no more than 320 horizontal rows of
pixels. This establishes a constraint that keeps VGA displays from
overwriting the command line, and keeps the format basically compatible
with HGC.
SCREEN COLORS
-------------
COLORS SUPPORTED
----------------
SPELLING HGC CGA EGA VGA
BLACK 0 x x(0) x x
BLUE 1 x x
GREEN 2 x x
CYAN 3 x x
RED 4 x x
MAGENTA 5 x x
BROWN 6 x x
LTGRAY 7 x x
DKGRAY 8 x x
LTBLUE 9 x x
LTGREEN 10 x(2) x x
LTCYAN 11 x x
LTRED 12 x(1) x x
LTMAGENTA 13 x x
YELLOW 14 x x
WHITE 15 x x(3) x x
NOTE: For HGC, all colors other than BLACK are forced to WHITE
For CGA, color indexes not marked with "x" are right-shifted
by two bits. I.e. "DKGRAY" which equals 8 (decimal) will become
color index 2, which will appear as LTGREEN. LTMAGENTA (13) will
become 3 (WHITE), etc. However, BLACK, LTGREEN, LTRED, and WHITE
will work well with CGA.
Therefore, if a drawing is to be presented to all users in an equal manner,
obviously only BLACK and WHITE are useful, and for the most part any filled
shapes should be kept as simple as possible. In some cases color can be
used, but only if the intent is such that either monochrome just will not
do, or when unexpected change of color also will not be serious.
As will be described below, the ".require" command can be used to constrain
operation of .GIL files with a particular adapter format. However, the
".require" commands can also be edited out in order to "try out" the files
in case of curiousity.
3.5 COMPUTER COMPATIBILITY ISSUES
----------------------------------
By definition GIL will use the graphics screen of your PC-style computer.
GIL will attempt to remember your default video modes and colors when it
executes, so that upon exiting back to DOS, GIL will clean up and reset
back to your defaults. But while GIL is executing, colors and modes
may be changed.
Every attempt has been made to make emergency termination of the program
possible whenever certain error conditions occur:
CTRL-C typed
CTRL-BREAK typed
Floating Point Error occurs (bugs, what bugs???)
Other abnormal conditions
When these actions occur, just before returning to DOS the program also
attempts to restore your screen back to the condition in which it was found
when GIL was invoked. However, there are no guarantees that this will always
be possible. Attempting to exit GIL with a BREAK or CTRL-C keystroke may under
some circumstances result in your video adapter being left in other than your
default operating state. Conditions that may make normal termination
impossible could possibly be caused by "other" Terminate and Stay Resident
(TSR) programs residing in memory. "Other" programs include the wrong
MSHERC.COM (in the case of your running a Hercules Graphics Adapter), or
something other than the suggested print screen TSRs (GRAPHICS.COM,
HPGRAPH.COM, EGAPRTSCRN, etc.).
At present GIL does not make use of either the COM or LPT ports of the
computer, nor does it write to disk. GIL requires DOS 3.3 or above,
and will run in less than 512K of memory. GIL should not care whether
it is executed from floppy or hard disk, since it assumes nothing but
standard DOX path arguments for seeking files or data.
GIL will also make use of the speaker device as a useful adjunct to
screen graphics. Again, the same conditions apply as above, regarding
aborting the program with "other" TSRs in memory. Under these conditions
aborting GIL with BREAK or CTRL-C might leave your speaker "ON" with a tone
running. If this happens, restart GIL interactively, and then ".bye" out
of it, or issue a short .beep command. In the extremely unlikely case
that the the problem now continues, then you will have to reboot your
computer.
In your CONFIG.SYS file, be sure to enable the ANSI.SYS device driver.
GIL does NOT require a co-processor. (A later release may permit faster
graphics using the co-processor.)
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
GIL (c) 1.01
COMMAND REFERENCE
-----------------
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
GENERAL NOTES ON COMMANDS:
--------------------------
A command is given to GIL as only one type of entry.
1.) A GIL executable command starts with the period, or dot, "."
2.) A "comment" is any ASCII text entered where the first character
in the first column is the "#" character. Comments will be
ignored.
3.) Empty lines consisting entirely of whitespace are ignored.
4.) Any other lines of ASCII text beginning with other than the "."
character will be treated as data or garbage, depending on the
context.
SPECIAL CHARACTERS
------------------
The use of "#" and "." have just been described.
UPPER CASE AND LOWER CASE
-------------------------
Commands can be either UPPER or LOWER case. In some commands requiring
alphanumeric, non-numeric, data, such as the ".color" command for color
specification, the alpha may be in UPPER or LOWER case also. The only
case sensitive input is the data you specify for the text to be displayed
in the ".text" command.
ERROR MESSAGES
--------------
In certain isolated cases when bad data or commands are entered, a
two-tone beep will occur to signal the user that display is otherwise
impossible.
For example, it is possible for the color parameter of the hue command
(such as BLACK) to cause display of the "GIL>" prompt to be in the same
color as the background color (entered with the ".backdrop" command).
After that, the user may get flustered and enter a new ".color" command
with a misspelled color parameter. Since the error message cannot
be displayed (it is also lost in the background color at this point) a
two-tone beep is one way to indicate an error message.
If bad command syntax occurs, error messages will be displayed on the
screen.
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
GENERAL COMMAND STRUCTURE
-------------------------
Most commands consist of the leading "." in column one, followed
by the command name, with no intervening spaces, and then a series
of numerical or text parameters. Except for extended commands,
the command entry is concluded by typing the ENTER key. Therefore
most command lines will be shorter than 80 columns. In fact, the
program assumes a default maximum of 80 columns per ASCII line
(40 for CGA).
After the command keyword, parameters are entered. Commands
and parameters can be separated by "white space", e.g. SPACE,
TAB, and/or also by the COMMA. This should allow "easy" formatting
of data by programs used to "assist" in generating polygons, lines,
etc.
Therefore, the following command structure exists for most of the
commands:
.command n1 n2 n3 n4 ... nk
where "command" is the keyword, and n1 through nk are numerical
or alphanumerical parameters. For the detailed command descriptions
below, this structure is important to understand now.
A few commands, such as .polygon and .wave, require something
in addition:
EXTENDED COMMANDS
-----------------
Some commands, such as ".polygon" and ".wave", will require so much data that
more than one line of data can be entered to fulfill the list. The lines of
data coming after such a command line will
(a) always be numeric, and
(b) must be terminated with the final ".end" command.
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
# comment lines
---------------
With a # as the first character in the line, ALL of the remaining line
is disregarded. However, it is a useful way to place information in the
file for debugging and explanation purposes.
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.arc3 n1 n2 n3 n4 n5 n6
----- -- -- -- -- -- --
Description This routine is based on the geometrical rule that a circle
can be drawn through any three points on the plane, thus the
name "arc" (draw an arc) concatinated with "3" (three points
determine the circle).
In this program the arc is drawn COUNTER-CLOCKWISE from the
first set of viewpoint coordinates (n1, n2) to the third set
of viewpoint coordinates (n5, n6). The important effects are
caused by the second set of coordinates, (n3, n4), which
determine the "bending" necessary to make the circle. NOTE:
after the circle is calculated, the only part displayed is
the part obeying the above rule. If the bending point is
in the portion of the circle that would require drawing
clockwise from (n1, n2) to (n5, n6) it will not actually
be part of the arc. Rather it will be part of the gap.
A problem can occur under certain conditions when the end
points of the arc or the bending point fall on coordinates
which cause division by zero. This can occur for instance
when n1 = n5 or n2 = n6. There are other combinations that
cause this also. Also, if the three points lie in a line,
there is no way to determine if the arc is concave or convex.
This program will examine the entered coordinates, and in
certain cases "dither" the coordinates by adding in a small
amount of random noise that is less than +/- 1.0 (width of
one pixel in floating point). The net effect should amount
to an indistinguishable error in the size of the arc.
The default or most recent drawing color is used for this curve.
Remarks Clipping at the edge of the viewport WILL occur for arcs
drawn to be larger than the viewport. This can be used to
advantage (like say you want to draw an artificial horizon),
or for zooming into a drawing. See description of clipping
elsewhere. If you want to draw the entire circle, then
draw one arc as per above, and then enter a second command
with the end points interchanged in the command line.
See Also .color, .ellipse
Defaults: n1 = 100, n2 = 100, n3 = 100, n4 = 100, n5 = 100, n6 = 100.
Net effect: either nothing or a small dot is drawn, depending
on the outcome of the random number routine.
Bugs Aliasing on the edges of the arc is NOT removed.
Very tiny circles will thus appear lumpy.
Example .arc3 300 100 200 50 100 100
To draw a full circle, the gap is filled in with
.arc3 100 100 200 50 300 100
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.aspect n1
------- --
Description Used to correct for the differences in aspect ratio of
different displays or adapters, such as VGA or HGC.
Also, .aspect can be used to "stretch" or "crunch" a
display for making "square" printouts with print utilities.
The parameter n1 is a floating point number, usually in
the range .7 to 1.5, used to expand or compress the vertical
scale of the drawing for better looks on some displays.
Numbers greater than 1.0 are expansions.
Remarks
See Also .require
Bugs Any problems are caused by the attempt to be all things
to all adapters.
Example .aspect 1.3
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.backdrop n1
--------- --
Description Used to set/change the default color for the background color
of the viewport. Lifetime of this command's effects last until
the next .backdrop command.
Remarks See previous pages for the color table used for the various
graphics adapters. See also the notes on compatibility between
adapters.
See Also .color
Bugs There are never enough colors. There is no orange. The
backdrop color affects the way these colors are displayed,
in ways you can best judge by experimentation.
Example .backdrop , LTGRAY
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.beep n1
----- --
Description Used to sound the speaker for the time duration n1.
n1 is an unsigned decimal integer. Units of n1 are
approximately tenths of a second.
Remarks Use of large values for n1 will result in LONG waits
and possible stares from other people around you.
See Also .pitch
Bugs See Remarks. Can you wear out a speaker? Under
some conditions (see text) aborting with CTRL-C or
CTRL-BREAK may leave the speaker permanently ON.
This usually should not be a problem, however.
Example .beep 10 gives a one second tone.
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.box n1 n2 n3 n4 (open box)
---- -- -- -- --
.fbox n1 n2 n3 n4 (filled box)
----- -- -- -- --
Description Used to draw a box, or rectangle, from coordinates of the
first point (n1,n2) to the coordinates of the second
point (n3,n4). Coordinates of both points are in viewport
coordinates.
Remarks The endpoints can lie outside the viewport. Active clipping
will ensure that only the portion of the line inside the
viewport will be shown.
See Also .polygon, .color
Defaults: n1 = 100, n2 = 100, n3 = 200, n4 = 200.
Bugs Aliasing effects ("zaggies") are NOT eliminated by this
program.
Example .box 23 49 800 300
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.bye
----
Description This command is used to exit GIL and return the screen
to the default DOS display.
Remarks This command is the recommended way to exit GIL while
in interactive mode. Using CTRL-C or CTRL-BREAK is
possible, but not recommended and may result in confused
screen setup or confused screen colors or a continuous
speaker tone when DOS returns control, although these are
very remote possibilities.
See Also
Bugs
Example .bye
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.cgatext n1
-------- --
Description This command is used to turn on a "fudge" factor for displaying
non-CGA files on CGA adapters, when ".text" lines would normally
call for characters in columns 41-80. This command, when
n1 = ON, will cause all text from .text commands to be shifted
to the left, such that the column address called for will be
divided by exactly 2, and rounded down if necessary. That is,
if the command ".text 10 50 Hello" is given, the result on the
screen will effectively be ".text 10 25 Hello".
Parameter n1 is not case sensitive and can be either:
n1 = ON or n1 = OFF
Remarks CGA screens are only half as wide (in pixels) as EGA, CGA, etc.
Thus graphics, when scaled to fit CGA, will not line up with
text, which is presently using row and columc text boundaries.
In addition, CGA pixels are twice as large (huge) when compared
to the other adapters, so even when text is placed only half as
far across the screen, it will often be also too high when
compared to the other adapters.
See Also .text
Bugs Therefore, per the remarks, the end result will only be close,
but not exact, and often will still not yet be satifactory.
Some incompatibilities between CGA and other adapters cannot
be totally "fudged" away.
Example .cgatext on
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.circle n1 n2 n3 (line circle)
------- -- -- --
.fcircle n1 n2 n3 (filled circle)
-------- -- -- --
Description Used to draw a circle in the viewport. The center of the
circle is at x = n1, y = n2. The radius is n3. The default
color is used for both the lined form and the filled disc
form.
Remarks Clipping at the edge of the viewport WILL occur for circles
drawn to be larger than the viewport. This can be used to
advantage (like say you want to draw an artificial horizon),
or for zooming into a drawing. See description of clipping
elsewhere.
See Also .color, .ellipse
Defaults The center is n1 = 150, n2 = 150, with a radius of
n3 = 100.
Bugs Aliasing on the edges of the circle is NOT removed.
Very tiny circles will thus appear lumpy.
Example .circle 250 283 100
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.color n1
------ --
Description Used to set/change the default color for all drawing
and filling operations that follow, until the next occurrence
of a .color command. Note that only one parameter is
accepted, and it must be a color per the table above, not
a numeric value. The lifetime of this color is until the
next .color command. This color ALSO affects the color
of the text and command line displays, as well as error
messages. It is not a good idea to make this color the
same as the backdrop color. EXCEPTION: if you want to
print the screen, making this color the same as the back-
drop color will "hide" the command line, thus removing
the annoyance of having the command line becoming part
of the drawing printed out.
Remarks See previous pages for the color table used for the various
graphics adapters. See also the notes on compatibility between
adapters.
See Also .backdrop
Bugs There are never enough colors. There is no orange. The
backdrop color affects the way these colors are displayed,
in ways you can best judge by experimentation.
Example .color RED
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.dot n1 n2
---- -- --
Description This command "sets" one pixel on the screen
using the current color (defined by the .color command)
at the viewport location x = n1, y = n2.
Remarks Can be used to place random dots in your colors of
choice on the screen.
See Also .color, .backdrop
Bugs Not very efficient for setting large numbers of pixels.
Example .pixel 83 237
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.ellipse n1 n2 n3 n4 n5 n6 (line ellipse)
-------- -- -- -- -- -- --
.fellipse n1 n2 n3 n4 n5 n6 (filled ellipse)
--------- -- -- -- -- -- --
Description Used to draw a ellipse in the viewport. The center of the
ellipse is at x = n5, y = n6 in viewport coordinates. This
routine can be used to draw an ellipse which is rotated
by some arbitrary angle of n3 degrees around its center point.
n1 = First axis length
n2 = Aspect ratio relative to first axis. This is a floating
point number from 0.0 to almost as large as you want.
n3 = Inclination, in degrees, of the first axis from
horizontal.
n4 = step angle in degrees. The algorithm used depends on
incrementing around the ellipse from 0 to 360 degrees
every n4 degrees. When n4 = 1 there is sufficient
detail that the ellipse looks smooth. Increments
such as 5 or 10 degrees also usually look reasonable.
However, increments such as 60 degrees can be used,
which results in some interesting polygons.
n5 = x axis location of center of ellipse in viewport
coordinates.
n6 = y axis location of center of ellipse in viewport
coordinates.
Remarks Clipping at the edge of the viewport WILL occur for ellipses
drawn to be larger than the viewport. This can be used to
advantage (like say you want to draw an artificial horizon),
or for zooming into a drawing. See description of clipping
elsewhere. Rotation of the ellipse is useful for generating
interesting effects.
See Also .color, .circle
Defaults First axis length n1 = 250,
Aspect ratio n2 = 1.00
First axis inclination = 0 degrees,
Step angle = 5 degrees,
Center is 500, 320.
Bugs Aliasing on the edges of the ellipse is NOT removed.
Very tiny ellipses will thus appear lumpy.
Example .ellipse 200 .7 45 3 300 373
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.init
-----
Description This command is used to clear the screen of all text
and graphics. The effect is nearly the same as the
DOS command CLS in DOS.
Remarks
See Also .backdrop
Bugs
Example .init
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.line n1 n2 n3 n4
----- -- -- -- --
Description Used to draw a line from the first point to the second
point, in the current color. The viewport coordinates of the
first point are x = n1, y = n2. The viewport coordinates
of the second point are x = n3, y = n4.
Remarks The endpoints can lie outside the viewport. Active clipping
will ensure that only the portion of the line inside the
viewport will be shown.
See Also .polygon, .color
Bugs Aliasing effects ("zaggies") are NOT eliminated by this
program.
Example .line 23 49 800 300
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.pitch n1
------ --
Description Used to define/redefine the default pitch frequency
for the tone generated by .beep. The value n1 is a
decimal integer for a frequency in Hertz
Remarks Low pitches are more tolerable with long beeps than
high pitches.
See Also .beep
Bugs Based on timer chip in your computer, and the clock
frequency of the timer chip. The actual pitch may
end up different than expected if your computer's timer
runs very fast or very slow.
Example .pitch 440
Another Example
.pitch 800
.beep 3
.beep 1 for the Morse code for "N"
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.polygon (open polygon)
--------
n1 n2 n3 n4 n5 n6 ... .end
-- -- -- -- -- -- ----
.fpolygon (filled polygon)
--------
n1 n2 n3 n4 n5 n6 ... .end
-- -- -- -- -- -- ----
Description Polygon is used to draw polygons. The end points of the
line segments of the polygon are determined by each
PAIR of coordinates, starting with (n1, n2). The number
of points determining the polygon can range up to 512.
Polygons having only one point are "dots". Polygons
having two points only are lines. (Interesting!)
Three points determine a triangle, etc. However, the
most useful features of polygons are when they are
a) Irregular
b) Involuted
Such polygons can be used to draw almost any shape.
See the provided examples for use of polygons.
Polygons are drawn or filled with the default color
or the color from the last .color command.
Special Note: Data points are entered continuously, line after line,
without regard for beginning a line with # or . In fact,
the use of . or # should be avoided inside the data,
but white space is permitted. The list is terminated with
one final entry, ".end" as below.
Remarks The .ellipse and .star commands in fact use the same
display routines as polygon.
See Also .end The .end command is used to terminate the
list of points, after which the program counts up
the list of points and begins drawing.
Bugs The standard C graphics library is used for polygon
filling. There are some examples (especially stars
with large numbers of points) where filled polygons
have slight zaggies on the edges that are caused by
the standard library routines.
Example .fpolygon
330 359 335 357 340 359 355 364 350 371 345 377 340 369
335 372 330 377 325 371 320 368 320 362 .end
draws the three towed foot of a bird.
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.require n1
-------- --
Description This command MUST be the first line in the data file
IF it is used. However, it does not necessarily have
to be used at all.
This command is used to warn the user that the data
that is going to come later is only compatible with
(requires) a certain type of graphics adapter, e.g.
it contains colors that only look right on a VGA.
The possible choices for n1 are:
VGA, OVGA, MCGA, EGA, OEGA, HGC, CGA, and OCGA.
The n1 values are NOT case sensitive, however.
When the "require" parameter (e.g. VGA) does not match
the adapter in the computer (e.g. HGC) the program
will prepare to terminate.
Remarks This is merely a control feature to help unwary users
by warning them if the file is incompatible with the
graphics adapter in their computer. It is usually
used to help users of monochrome adapters who would
otherwise run color graphics data through the program
and receive an all white set of polygons and graphics
that would be fairly unglorious. It can also be used
to indicate that the aspect ratio may not be right.
E.g. graphics and text may become misaligned if run
through the wrong adapter. The whole line can be removed
from the file, or commented out with #, in order to
remove its effect.
See Also .aspect
Bugs
Example .require VGA
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.star n1 n2 n3 n4 n5 (open star)
----- -- -- -- -- --
.fstar n1 n2 n3 n4 n5 (filled star)
------ -- -- -- -- --
Description Used to draw a star-shaped polygon. The coordinates
of the center of the star are n1, n2. The radius of
the outer circle of points of the star is n3. The radius
of the points forming the notches is n4. The number
of points of the star is n5. The range of n5 runs from
3 to 512.
Remarks The endpoints can lie outside the viewport. Active clipping
will ensure that only the portion of the line inside the
viewport will be shown. A 512-pointed star is a lot
of points!
See Also .polygon, .color
Defaults: n1 = 500, n2 = 300, n3 = 250, n4 = 80, n5 = 5.
Bugs Aliasing effects ("zaggies") are NOT eliminated by this
program. Especially, large filled stars with many points
will have some strange effects due to the filled polygon
routine from the C library.
Example .star 500 300 200 50 28
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.text n1 n2 n3
----- -- -- --
Description This command is used to place text on the screen in the
middle of the graphics display.
n1 = row coordinates of text ( 1 to 22 ).
n2 = column coordinates of the first letter of the
text ( 1 to 80 for all adapters except
CGA, and 1 to 40 for CGA adaptors).
n3 = any text in ASCII, even if containing more than
one word. If you want this file to work with
CGA as well as others, and you are editing it
on something else besides CGA, try not to make
the length of the text on n3 longer than 40
characters.
Remarks Alignment with graphics can be somewhat problematic.
These routines attempt to serve all graphics adapters.
CGA adapters, which have such large text characters,
will always be even more problematic.
See Also .cgatext
Bugs The C library used does not have the ability to
output generic BIOS character generator text in just
any location on the graphics screen. BIOS characters
are forced to reside on text coordinates. This is a major
problem, which until solved, makes alignment of text and
graphics problematic, especially when this program attempts
to work on all graphics adapters. "Personal Engineering"
magazine recently discussed this issue. Real graphics
fonts from the C compiler are available, but these require
payment of a royalty to BITSTREAM, which is not going to
be compatible with the idea here of free software.
Examples .text 4 8 The quick brown fox jumped
.text 7 20 ~We the people
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.trace n1
------ --
Description Trace is used to select whether or not to display the
entire array of parameters from a ".polygon" or ".wave"
command, or to skip the display beyond the first line.
If trace is on, each line of parameters is displayed
successively, as parsed, on line 23. If trace is not
on, the parse is done "silently".
Parameter n1 is not case sensitive and can be either:
n1 = ON or n1 = OFF
Remarks Trace is useful for finding "bad spots" in a parameter
list.
See Also .polygon and .wave
Bugs Unfortunately, if the file contains a long list of coordinate
parameters, turning on trace will consume more time while the
display routines print the text one line at a time on line 23.
Example .trace on
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
.wave
-----
n1 n2 n3 n4 n5 n6 ... .end
-- -- -- -- -- -- ----
Description Wave is used to draw waveforms or a long set of contiguous
linked line segments. The end points of the line segments
of the polygon are determined by each PAIR of coordinates,
starting with (n1, n2). The number of points determining the
waveform can range up to 512. For drawing graphs or waveforms,
this routine does NOT perform curve fitting, smoothing,
or draw with Bezier or B-spline techniques. SPECIAL NOTE:
the y-azis coordinate system starts at the top of the screen,
not the bottom. This should be taken into account when
other programs are used to calculate the set of points and this
program is used to graph the waveform, using .box, .fbox,
.text, and .wave.
Waves are drawn or filled with the default color
or the color from the last .color command.
Special Note: Data points are entered continuously, line after line,
without regard for beginning a line with # or . In fact,
the use of . or # should be avoided inside the data,
but white space is permitted. The list is terminated with
one final entry, ".end" as below.
Remarks This is similar to the .polygon command.
See Also .end The .end command is used to terminate the
list of points, after which the program counts up
the list of points and begins drawing.
Bugs This may not be the most comfortable way to actually
draw a graph of some data, since the y coordinate
starts at the top of the screen, not the bottom.
Example .box 1 1 600 400
.wave 1 200 100 160 200 230 300 180 400 330
500 200 599 400 .end
GIL COMMAND REFERENCE Copyright (c) 1991 Glenn L. Williams
Possible future commands:
Commands that make thick lines. But such commands need to execute very
quickly! The only way to make thick lines right now is to draw them
by laying down parallel lines.
Commands to draw "waveforms" and "zig-zags" with cubic spline, Bezier
spline, or B-spline methods. "Splines" are methods similar to drawing
with a "french curve" on paper.
Better graphics text characters. "Personal Engineering" magazine
recently discussed this issue.