Category : C Source Code
Archive   : POLY3DRS.ZIP
Filename : POLY3D-R.DOC

POLY3D-R - 3d polygonal rendering program
-----------------------------------------

BECAUSE POLY3D-R IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO
WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING, I GERSHON ELBER PROVIDE POLY3D-R PROGRAM "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU. SHOULD THE POLY3D-R PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
ELBER) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.


A program to render a given polygonal model into GIF image file format,
using cosine shading approximation, and flat/Gouraud interpolation. The
program does 4 passes over the input:

1. Process the input (parsing.)
2. Prepare the polygons by sorting them by their Y after mapping then into
screen space.
3. Evaluate colors for vertices (using polygon normals if flat shading, or
by averaging normals for Gouraud shading).
4. Scan the data by scan line basis and dump out image.

This programs can handle CONVEX polygons only. See poly3d.doc,
Appendix A, for exact text format definition. From irit given object O,
issue the command 'O = convex(O);' to make sure object has convex polygons
only before dumping it out.

Options:
--------

poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize] [-g] [-b]
[-S n] [-M Mask] [-o Objects...] [-v ViewFile] [-z] DFiles > Image.GIF

-a Ambient : Sets the ambient intensity (must be in [0..1] range).
-c N : number of bits per pixel N (must be in [1..8] range).
-l X Y Z : specify the light source normal direction. This vector does not
to be unit vector.
-2 : Force 2 light sources at opposite directions as selected via [-l]. This
may be useful for models that has no plane specified (i.e. model has no
PLANE attribute for its polygons), as the program guess the equation from
the points themselves, and which can be to the opposite direction.
-m : More - give some more information on the data file(s) parsed.
-s Xsize Ysize : specify image dimensions. As the models created by IRIT
or DrawFn3D are mapped to a unified domain (X::[-1..1], Y::[-1..1]) by the
viewing matrix (see [-v]), image must be scaled up. The scaling up factor
is MIN(Xsize, Ysize), which guarantee nothing of the original image will be
clipped.
-b : Delete back facing polygons. If the scene contains objects with complete
boundary (such as the ones IRIT solid modeler generates), the back facing
polygons can be deleted. This would not change the image, but will speed
up the process at about %15. Using this option for non complete boundary
object and/or objects with polygons with no PLANE specified (such as the
ones DrawFn3D generates) would almost definitely create wrong image.
-g : Use Gouraud shading interpolation (flat shading is used by default).
This is somewhat slower, but gives nicer results.
-S n : sub sample, and used box filter to filter the image, using n as
grid side of n by n. This obviously make things slower, but guess what -
it looks much better.
-M Mask : Create a new GIF file named Mask that is a binary image set to 1
at any pixel covered by one of the objects or 0 otherwise. As a color of
an object can become equal to the background at some point, there is no
why to find whether pixel is background or an object in the background
color. The Mask can be used instead. This Mask can be used when combining
images (such as GifComp utility in the Gif_Lib).
-o Object(s) : Objects to display (all by default). Object is the name as
appears after the OBJECT key word the data files
(do 'grep OBJECT datafile'...).
-v ViewFile : View file - file of the view matrix transformation
-z : Print version number and current defaults.

The image is dumped to stdout as a GIF image which can be redirected to a
file or to be piped to any program that reads GIF images from stdin.

Configuration:
--------------
The program can be configured using a configuration file named poly3d-r.cfg.
This is a plain ascii file you can edit directly and set the parameters
according to the comments there. executing 'poly3d-r -z' will show the
current configuration as read from the configuration file. This file can be
in any directory which is in your path - the same place as poly3d-r.exe is
probably a good choice.

MSDOS version:
The program will use 80?87 if it detects one - uses the Turbo C 80?87
autodetect, or will run (much!) slower without it...

Usage:
------
As this program is not interactive, usage is quite simple, and only
control available is using the command lines options.

Notes:
------
1. If the input file is ill, i.e. some polygons are degenerated, (2 vertices
are identical etc.) they will be ignored is the next passes. Use [-m] if
you want to see them.
2. Although not supported by other programs, it might be useful to specify
the exact RGB color for a given OBJECT. This program adds a new attribute
named RGB but with 3 integer components (the regular one with one index
color - see poly3d-r.cfg, is also supported) to the .'PLY' text data
files: [RGB R G B]. Each of R G B must be integer is the range [0..255].

Bugs:
-----
O.k. if you do have any question, suggestion, or even want to report a bug
feel free to send me Email (see below)

Feel free to make copies of this program, and distribute them FREE of
charge, provided that all this package is distributed.
I am not going to be responsible for any damage of any kind, that this
package may cause (I always wanted to say that...), but I hope you will
enjoy it as I did my best you will. At list I enjoyed writing it.

Have Fun

Gershon Elber
[email protected]