3D-PLOT USER DOCUMENTATION
version 1.2
(C) Copyright 1990, 1991 REALware


PURPOSE
This program plots three-dimensional images made of points, lines, and
circles contained in an "image file" onto the screen with proper
perspective. These image files are created with the use of a standard
ASCII file editor (even a DOS utility such as EDLIN or COPY CON: will
suffice), with an easy-to-use pseudo-language. General information,
such as the default observer's coordinates and facing, and your
monitor's aspect ratio may be kept in one or more "definition files."


REQUIREMENTS
o DOS 2.0 or higher
o a graphics monitor (CGA, EGA, VGA, Hercules, etc.)
Note that 3D-PLOT uses the BGI file drivers contained with
Turbo C* and other Borland products. You must either have the
proper files corresponding to your graphic device in the
current working directory or in a directory whose name you
specify to 3D-PLOT as a command argument. See USAGE.
o adequate memory available (128K should be sufficient)


USAGE
Information such as image file to plot, definition file(s), and the
BGI path are passed to 3D-PLOT via the command arguments. If the
program is able to continue, then it will draw the image requested.
When finished, plotting will stop, and the user can hit any key to
return to DOS.
The program takes the following arguments:

C> 3D-PLOT [ [...]] []

:
The image file which to plot. This parameter must be specified
for 3D-PLOT to draw anything. Image files by default have a .3D
extension. Files that do not have a specified extension (i.e., do
not have a period character in them) will by default be given the
suffix .3D.
If the image file is "stdin," 3D-PLOT will use the standard
input stream as the image file.
[...]:
The definition file or files (there can be multiple definition
files if desired) to use when plotting. Definition files by
convention have the file extension .DEF; files that do not have a
specified extension (as above) will by default be given the suffix
.DEF. If no definition files are specified, then the file
STANDARD.DEF will be used automatically.
:
The location of the BGI graphics drivers used with Turbo C that
3D-PLOT requires to perform. This directory, if specified, must
end in a backslash character (\). If this parameter is not
specified, then 3D-PLOT uses the current working directory. Note
that you only need the graphic driver corresponding to the
hardware you have. For instance, if you have CGA, then you only
need the CGA.BGI file to be located in the specified directory.

Examples:
3D-PLOT CUBE
o Plot the image file CUBE.3D, using STANDARD.DEF as the
definition file, and the current working directory as the BGI
path.
3D-PLOT GRID NEW.DEF
o Plot the image file GRID.3D using NEW.DEF as the definition
file, and the current working directory as the BGI path.
3D-PLOT GLOBE.3D \TC\
o Plot the image file GLOBE.3D, using STANDARD.DEF as the
definition file, and \TC\ as the BGI path.
3D-PLOT TEST ASPECT ZOOM C:\BORLAND\BGI\
o Plot the image file TEST.3D, using ASPECT.DEF and ZOOM.DEF for
definition files, and C:\BORLAND\BGI\ as the BGI path.


THE DATA FILES
3D-PLOT uses two types of data files to plot its images. These are
_image files_ and _definition files._ They are simple text files,
which contain a pseudo-programming language that 3D-PLOT can
understand and use. There are two kinds of instructions: definition
instructions and image instructions. Image data is _only_ found in
image files (.3D), while definition data can be found in both image
files and definition files (.DEF). Defintion data tells 3D-PLOT _how_
to draw things, while image data tells 3D-PLOT _what_ to draw.
Each instruction is placed on one line; unrecognized instructions,
commented lines (those beginning with a pound sign [#] or a semicolon
[;]), and blank lines are ignored. In addition, an instruction with
two few arguments will cause an error. (Extra arguments will be
ignored.)
3D-PLOT reads and carries out the instructions in each file in one
at a time, starting with the first definition file specified. (If no
definition file is specified, 3D-PLOT reads in the STANDARD.DEF file.)
After 3D-PLOT has finished with the definition file(s), it reads the
image file and carries out the instructions contained therein. When
the first image instruction (see below) is encountered, 3D-PLOT
initializes the graphics screen and begins plotting. When finished,
3D-PLOT waits for the user to press a key to return to DOS. (Note
that the user can press ESC at any time while 3D-PLOT is drawing an
image to cancel and return to DOS.)
The definition instruction that is read last takes precedence over
similar instructions read previously. For instance, an OBSERVER
instruction in the first definition file will be overridden by an
OBSERVER instruction in the second definition file (if there is one)
or the image file. The same argument goes for all other definition
instructions.


DEFINITION INSTRUCTIONS
There are four definition instructions, which can be located either in
definition or image files:

OBSERVER x y z
o This instruction specifies the location of the observer (that
is, where your computer monitor is located. The arguments are
the x-, y-, and z-component of the standard three-dimensional
Cartesian coordinates that the observer is located at. For
instance, the instruction OBSERVER 1 1 1 would indicate to 3D-
PLOT that the observer is to be located at the point (1, 1,
1).

FACING [x y z]
o This instruction indicates to 3D-PLOT where the observer is to
be _looking._ It is represented as the standard three-
dimensional Cartesian coordinate that the observer would be
looking at. FACING alone on a blank line (no arguments) will
default to (0, 0, 0). Note that having the same coordinate
specified in both OBSERVER (above) and FACING will result in
an error. A FACING instruction must follow an OBSERVER
instruction.

SCALE [s]
o This is a measure of how large an object looks on the screen.
Values of 300 to 500 are optimal, while very large numbers
correspond to very high magnification, and very smaller
numbers will give the image a "fish-eye" (wide-field) look.
SCALE defaults to 400.

ASPECT [x [y]]
o This instruction specifies the aspect ratio of computer
monitor. It takes two arguments, x and y. Leaving the y
parameter off of an ASPECT instruction will cause the y
parameter default to 1. ASPECT alone on a blank line (no
arguments) will default both arguments to 1.
An aspect ratio is a measure of the dimensions of each
individual pixel on your monitor. Since 3D-PLOT assumes that
your screen pixels are actually square (which is only the case
in VGA), deviations from this standard will result in images
that look "stretched" or "squashed." The best way to find
your aspect ratio is to experiment. Check the image file
ASPECT.3D for more information.
It is recommended that you have a separate definition file
for the aspect ratio -- probably named ASPECT.DEF. Thus,
whenever you run 3D-PLOT you can always use that definition
file as the first definition file argument (you might want to
set up a batch file as well), without having to alter all of
the definition files that you have as you get them.


IMAGE INSTRUCTIONS
Image instructions are used to actually draw the image. Note that you
may use the OBSERVER, FACING, ASPECT, and SCALE instructions in image
files to override the instructions specified in the definition
file(s). All of the definition instructions should be processed
_before_ any image data instructions are. Image data instructions
are:

POINT x y z
o This instructions plots a pixel at the point (x, y, z).

DOT x y z
o This instruction draws a very small circle at the point (x, y,
z). In some cases this might be preferable to POINT, since on
some monitors it is hard to see individual pixels.

LINE x1 y1 z1 x2 y2 z2
o This draws a line from the point (x1, y1, z1) to (x2, y2, z2).

RELLINE x2 y2 z2
o This instructions draws a line from the last point plotted
with a POINT, DOT, CIRCLE (the center), or with the second
coordinate of LINE) to the point specified by (x2, y2, z2).
This makes it easy to draw continuous lines, such as polygons:
they merely consist of one LINE instruction and several RELLINE
instructions, which might rejoin with the starting point of
the LINE instruction.

CIRCLE x y z r
o This plots a sphere (which appears as a circle on the screen)
with center (x, y, z), with radius r. Circles should appear
round even if the aspect ratio is not set properly.

COLOR c
o Change the drawing color to c. This is a number, and
depending on your system, it may represent different colors.
See REFERENCE: PALETTES AND COLORS. (Color 0 is always the
background color; it can be used to erase figures already
drawn.)

The best way to learn how to use something is to experiment. See the
individual image files for examples.


REFERENCE: ERROR CONDITIONS
The possible errorlevels that 3D-PLOT may return are:

0 Normal program termination.

-1 Invalid command line arguments. There were not enough command
line arguments included when running 3D-PLOT to continue.

-2 File not found. One of the definition or image files was not
available for opening.

-3 Instruction not understood. An instruction was either not
understood or had the wrong number of arguments.

-4 Observer not defined. An image instruction was encountered
before the observer's position was specified. Also, this
errorlevel will be set if the OBSERVER instruction has invalid
arguments. This will also be set if a FACING instruction
appears before an OBSERVER instruction.

-5 Definition instruction encountered after image instruction.
definition instructions should be located before any image
instructions.

-6 Graphics error. There was a graphics-intensive error and 3D-
PLOT could not continue. (Most likely it was an incorrect BGI
path.)


REFERENCE: SUPPORTED GRAPHICS SYSTEMS**
Here are the graphics systems supported by 3D-PLOT. 3D-PLOT will
automatically select the highest graphics resolution available.

Graphics Graphics Screen size Palletes Colors per Pages+ BGI file
driver mode (pixels) palette required

CGA CGACx 320x200 4 4 1 CGA.BGI
CGAHI 640x200 -- 2 1

MCGA MCGACx 320x200 4 4 1 MCGA.BGI
MCGAMED 640x200 -- 2 1
MCGAHI 640x480 -- 2 1

EGA EGALO 640x200 -- 16 4 EGAVGA.BGI
EGAHI 640x350 -- 4 1

EGAMONO EGAMONOHI 640x350 -- 2 1++ EGAVGA.BGI
EGAMONOHI 640x350 -- 2 2+++

HERC HERCMONOHI 720x348 -- 2 2 HERC.BGI

ATT400 ATT400Cx 320x200 4 4 1 ATT.BGI
ATT400MED 640x200 -- 2 1
ATT400HI 640x400 -- 2 1

VGA VGALO 640x200 -- 16 2 EGAVGA.BGI
VGAMED 640x350 -- 16 2
VGAHI 640x480 -- 16 1

PC3270 PC3270HI 720x350 -- 2 1 PC3270.BGI

IBM8514 IBM8514HI 640x480 -- 256 -- IBM8514.BGI
IBM8514LO 1024x768 -- 256 --
----------
+ Pages are currently not used with 3D-PLOT version 1.2.
++ 64K on EGAMONO card.
+++ 256K on EGAMONO card.


REFERENCE: PALETTES AND COLORS***
Valid color values are:

On CGA systems:
Palette Color number
number 1 2 3
0 LIGHT_GREEN LIGHT_RED YELLOW
1 LIGHT_CYAN LIGHT_MAGNETA LIGHT_WHITE
2 GREEN RED BROWN
3 CYAN MAGNETA WHITE

On EGA or VGA systems:
Color Color number
BLACK 0
BLUE 1
GREEN 2
CYAN 3
RED 4
MAGNETA 5
BROWN 6
WHITE 7
DARK_GRAY 8
LIGHT_BLUE 9
LIGHT_GREEN 10
LIGHT_CYAN 11
LIGHT_RED 12
LIGHT_MAGENTA 13
YELLOW 14
LIGHT_WHITE 15 (BRIGHT WHITE)

Note: If you have a non-standard EGA or VGA card, you may


HISTORY
1.2. 15 October 1991. Major changes. COLOR and PALETTE added;
multiple definition files allowed. See 3DPLOT12.NEW for a
complete list.
1.1.2. 14 October 1991. Program made more user-friendly; instead of
crashing, 3D-PLOT now halts and prints a message (it used to
not exit graphics, and so the screen would be affected with
garbage).
1.1.1. 27 June 1991. Minor bugfix version.


PUBLIC LICENSE
This program is freeware. You may share this program freely with
others, provided that:
1. you do not modify the programs, documentation, or
supplementary files that came with your copy in any way;
2. the program, documentation, and supplementary files are
contained in the same archive or directory, and no charge is
administered for distribution, save the cost of the
distribution media itself (disks, paper, etc.).
Users are encouraged to create their own image files and distribute
them. However, we at REALware ask that you distribute them separately
from 3D-PLOT itself -- that is, don't pass them along in the same
archive or directory.


DISCLAIMER
These program and all of its documentation are distributed on an "as-
is" basis. Both the author and REALware assume absolutely no
liability for any damage incurred by the use of this program, either
directly or indirectly.


THE AUTHOR
This REALware program was written by Max Pandaemonium. The
source code may made available at a later date. Comments, questions,
bug reports, etc. are encouraged. Send your comment (by US Mail or
Usenet mail -- Usenet preferred) to:
Max Pandaemonium
1070 Oakmont Dr., Apt. #1
San Jose, CA 95117
Internet: [email protected]
UUCP: ..!apple!uuwest!max


----------
* Turbo C and Borland are trademarks of Borland International, Inc.
** Reprinted from _Turbo C Reference Guide_ page 203
*** Reprinted from _Turbo C User's Guide_ page 243

-)(-