home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / IRIT / POLY3DRS.ZIP / POLY3D-R.DOC < prev    next >
Encoding:
Text File  |  1990-05-05  |  6.4 KB  |  128 lines
  1.     POLY3D-R - 3d polygonal rendering program
  2.     -----------------------------------------
  3.  
  4.   BECAUSE POLY3D-R IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO
  5. WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN
  6. OTHERWISE STATED IN WRITING, I GERSHON ELBER PROVIDE POLY3D-R PROGRAM "AS IS"
  7. WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
  8. NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  9. PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  10. PROGRAM IS WITH YOU. SHOULD THE POLY3D-R PROGRAM PROVE DEFECTIVE, YOU ASSUME
  11. THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  12.  
  13.   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
  14. BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
  15. OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  16. USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
  17. FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
  18. ELBER) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
  19. SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  20.  
  21.  
  22.     A program to render a given polygonal model into GIF image file format,
  23. using cosine shading approximation, and flat/Gouraud interpolation. The
  24. program does 4 passes over the input:
  25.  
  26. 1. Process the input (parsing.)
  27. 2. Prepare the polygons by sorting them by their Y after mapping then into
  28.    screen space.
  29. 3. Evaluate colors for vertices (using polygon normals if flat shading, or
  30.    by averaging normals for Gouraud shading).
  31. 4. Scan the data by scan line basis and dump out image.
  32.  
  33.     This programs can handle CONVEX polygons only. See poly3d.doc,
  34. Appendix A, for exact text format definition. From irit given object O,
  35. issue the command 'O = convex(O);' to make sure object has convex polygons
  36. only before dumping it out.
  37.  
  38. Options:
  39. --------
  40.  
  41. poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize] [-g] [-b]
  42.     [-S n] [-M Mask] [-o Objects...] [-v ViewFile] [-z] DFiles > Image.GIF
  43.  
  44.   -a Ambient : Sets the ambient intensity (must be in [0..1] range).
  45.   -c N : number of bits per pixel N (must be in [1..8] range).
  46.   -l X Y Z : specify the light source normal direction. This vector does not
  47.      to be unit vector.
  48.   -2 : Force 2 light sources at opposite directions as selected via [-l]. This
  49.      may be useful for models that has no plane specified (i.e. model has no
  50.      PLANE attribute for its polygons), as the program guess the equation from
  51.      the points themselves, and which can be to the opposite direction.
  52.   -m : More - give some more information on the data file(s) parsed.
  53.   -s Xsize Ysize : specify image dimensions. As the models created by IRIT
  54.      or DrawFn3D are mapped to a unified domain (X::[-1..1], Y::[-1..1]) by the
  55.      viewing matrix (see [-v]), image must be scaled up. The scaling up factor
  56.      is MIN(Xsize, Ysize), which guarantee nothing of the original image will be
  57.      clipped.
  58.   -b : Delete back facing polygons. If the scene contains objects with complete
  59.      boundary (such as the ones IRIT solid modeler generates), the back facing
  60.      polygons can be deleted. This would not change the image, but will speed
  61.      up the process at about %15. Using this option for non complete boundary
  62.      object and/or objects with polygons with no PLANE specified (such as the
  63.      ones DrawFn3D generates) would almost definitely create wrong image.
  64.   -g : Use Gouraud shading interpolation (flat shading is used by default).
  65.      This is somewhat slower, but gives nicer results.
  66.   -S n : sub sample, and used box filter to filter the image, using n as
  67.      grid side of n by n. This obviously make things slower, but guess what -
  68.      it looks much better.
  69.   -M Mask : Create a new GIF file named Mask that is a binary image set to 1
  70.      at any pixel covered by one of the objects or 0 otherwise. As a color of
  71.      an object can become equal to the background at some point, there is no
  72.      why to find whether pixel is background or an object in the background
  73.      color. The Mask can be used instead. This Mask can be used when combining
  74.      images (such as GifComp utility in the Gif_Lib).
  75.   -o Object(s) : Objects to display (all by default). Object is the name as
  76.      appears after the OBJECT key word the data files
  77.      (do 'grep OBJECT datafile'...).
  78.   -v ViewFile : View file - file of the view matrix transformation
  79.   -z : Print version number and current defaults.
  80.  
  81.   The image is dumped to stdout as a GIF image which can be redirected to a
  82. file or to be piped to any program that reads GIF images from stdin.
  83.  
  84. Configuration:
  85. --------------
  86.   The program can be configured using a configuration file named poly3d-r.cfg.
  87.   This is a plain ascii file you can edit directly and set the parameters
  88. according to the comments there. executing 'poly3d-r -z' will show the
  89. current configuration as read from the configuration file. This file can be
  90. in any directory which is in your path - the same place as poly3d-r.exe is
  91. probably a good choice.
  92.  
  93.   MSDOS version:
  94.   The program will use 80?87 if it detects one - uses the Turbo C 80?87
  95. autodetect, or will run (much!) slower without it...
  96.  
  97. Usage:
  98. ------
  99.   As this program is not interactive, usage is quite simple, and only
  100. control available is using the command lines options.
  101.  
  102. Notes:
  103. ------
  104.   1. If the input file is ill, i.e. some polygons are degenerated, (2 vertices
  105.      are identical etc.) they will be ignored is the next passes. Use [-m] if
  106.      you want to see them.
  107.   2. Although not supported by other programs, it might be useful to specify
  108.      the exact RGB color for a given OBJECT. This program adds a new attribute
  109.      named RGB but with 3 integer components (the regular one with one index
  110.      color - see poly3d-r.cfg, is also supported) to the .'PLY' text data
  111.      files: [RGB R G B]. Each of R G B must be integer is the range [0..255].
  112.  
  113. Bugs:
  114. -----
  115.   O.k. if you do have any question, suggestion, or even want to report a bug
  116. feel free to send me Email (see below)
  117.  
  118.   Feel free to make copies of this program, and distribute them FREE of
  119. charge, provided that all this package is distributed.
  120.   I am not going to be responsible for any damage of any kind, that this
  121. package may cause (I always wanted to say that...), but I hope you will
  122. enjoy it as I did my best you will. At list I enjoyed writing it.
  123.  
  124. Have Fun
  125.  
  126. Gershon Elber
  127. gershon@cs.utah.edu
  128.