gondwana.ecr.mu.oz.au/pub//Graphics.tar/Graphics/oort10.zip/README

Text File | 1993-12-07 | 16KB | 373 lines

              OORT - Object Oriented Ray Tracer
                   Disk Set Documentation
                         Version 1.0

        OORT is copyright (C) 1994 by Nicholas Wilt.

This software product may be freely copied and distributed
in unmodified form but may not be sold.  A nominal
distribution fee may be charged for media and handling by
freeware and shareware distributors.  The software product
may not be included in whole or in part into any commercial
package without the express written consent of the author.

This software product is provided as is without warranty of
any kind, express or implied, including but not limited to
the implied warranties of merchantability and fitness for a
particular purpose.  The author assumes no liability for any
alleged or actual damages arising from the use of this
software.  The author is under no obligation to provide
service, corrections or upgrades to this software.


     Despite the disclaimer above, I welcome suggestions and
feedback on OORT.  Please feel free to contact me at my
CompuServe address (75210,2455 or [e-mail]
from the Internet).

     This distribution contains the source code that
accompanies my book, _Object-Oriented Ray Tracing in C++_.
If you are interested in ray tracing, or if you want to
understand OORT in more detail, you can call John Wiley &
Sons at 1-800-CALLWILEY (1-800-225-5945) to order it.
Alternatively, you can find it in a local bookstore or
have them order it for you (ISBN 0471 304 158, $36.95).

     The book assumes some knowledge of 3D computer
graphics.  It includes lots of references so readers can
pursue their own research, too.  The topics covered include
the following:

     -    Vectors and matrices for computer graphics.
     -    Standard Hall shading model with ambient, diffuse,
          specular, reflective and transparent components.
     -    Rendering various primitives (planes, rings,
          polygons, spheres, bounding boxes, quadrics, CSG
          and algebraic surfaces).
     -    Ray tracing acceleration.  OORT implements
          Goldsmith and Salmon's automatic bounding volume
          hierarchy generation for speed.  It also includes
          a hand-coded 80x87 assembler routine to intersect
          a ray with a bounding box.
     -    Texture mapping.  Procedural and solid texturing
          is described.  OORT implements a bunch of inverse
          mappings (sphere, cone, cylinder, quadrilateral,
          circle).
     -    Distribution ray tracing for antialiasing, soft
          shadows, and imperfectly reflective and
          translucent objects.
     -    Statistical optimization to make the distribution
          ray tracing go faster.

     OORT is a class library for ray tracing.  As such, it
does not implement an input language or interactive user
interface. Currently, images are described to the ray tracer
using calls into the class library.  This is surprisingly
painless; unlike C code, C++ is almost as intuitive as the
input language of a ray tracer.  In addition, C++ is much
more powerful than any ray tracer input language; it has
loop constructs, functions and support for abstract data
types.  Finally, C++ debugging tools are much more
sophisticated than the debugging tools that are available
for proprietary ray tracer input languages.
     All these protestations are not to say that no
interactive user interface for OORT is in the works.  I plan
to develop an interactive user interface for OORT, and may
provide parsers for other ray tracers' input languages.  But
for now, if you want to make pictures using OORT, you have
to develop in C++.

The directory structure is as follows:
README         This file documents the disk contents.
OORT\          Contains the OORT class library and
               examples.
  EXAMPLES\    Contains a variety of examples usages of
               OORT.  Each example is in its own
               subdirectory.
  INCLUDE\     Contains include files for OORT.
  LIB\         Library directory.  This will contain the
               OORT library after it has been built.
  SOURCE\      Contains implementation files for OORT.
  UTILS\       Contains source code for the Utilities
               library for OORT.
RAW2GIF\       Contains source code and compiled
               executables for RAW2GIF, a program that
               converts OORT output files to the popular
               GIF format.
SPLICE\        Contains source code for Splice, a program
               that splices together multiple .RAW files
               that are portions of the same image.

     To use OORT, you must first copy it to its own
subdirectory and build it.  You can use the PKUNZIP command
to uncompress the contents of the distribution as follows:
     pkunzip -d oort10.zip
The -d parameter instructs PKUNZIP to copy subdirectories.
The above command will copy the entire disk onto your hard
drive, creating root directories named OORT, RAW2GIF, and
SPLICE.  If you want to use RAW2GIF or SPLICE, you may want
to add the appropriate directories to your path.

OORT was developed and tested using Borland C++, so all of
the following descriptions apply to that development
environment.

Overview

     For more information on developing with OORT, please
refer to Appendixes E-G of my book, Object-Oriented Ray
Tracing in C++.

To render images using OORT, you must follow these steps in
     order:
1) Build the library.
2) Build the utilties library.
3) Build an OORT application that links against the library.
  The EXAMPLES directory contains a number of these.)
4) Run the application.  You can provide command-line
  arguments to this application to change the resolution of
  the target image, turn on antialiasing, etc.  When it
  completes successfully, this program will generate an
  output file with the default extension .RAW.
5) Run RAW2GIF on the resulting .RAW to convert it to GIF
  format.
6) Display the GIF image on your screen using a GIF viewer.

     These steps are detailed below.

1) Build the library.

     Before using OORT, you must build the library.  Change
to the OORT implementation directory by typing:
     cd \oort\source
If you want to run OORT under Windows, type
     make -fmakefile.win
If you want to run OORT under DOS, type
     make -fmakefile.dos

Be sure you are executing Borland's Make utility on these
makefiles.  Other Make utilities are not guaranteed to work!

The makefiles can be tweaked if the default settings are not
satisfactory.  The following variables are defined in the
makefile to build OORT:

INCLUDES       Gives -I command lines as needed, to
               specify directories where the compiler can
               find include files.  The default is
               "..\include", which will work as long as
               you copied the files exactly as they were
               on the diskette.
LIBDIR         Gives the directory to write the library
               to.  The default is "..\lib".  Make sure
               there is an empty directory \OORT\LIB on
               your disk.
WARNS          Turns off some of the more tiresome
               compiler warnings, such as "possibly
               incorrect assignment."
MODEL          Memory model to use.  The default is large
               (-ml).
OPTS           Optimizations to use.  The default is "no
               optimization" (-Od).  To turn on maximum
               optimization, comment out the line "OPTS=-
               Od" and remove the comment for the other
               optimizations line, which contains the
               following arguments:

               -vi       Enable inline functions
               -Ox       Maximum optimization
               -386      386 or better target machine
               -DASM     Enable assembler
               -f87      Coprocessor in target machine

               Remove "-3" if you are targeting 286 or
               earlier machines.  Remove "-f87" if you
               want OORT to run on machines without
               coprocessors (a masochistic endeavor).

After successfully building OORT, you should have a file
called OORT.LIB in the LIB directory of your OORT directory
structure.

2) Build the Utilities library.

To build the Utilities library, switch directories to
\OORT\UTILS.  If you want to run OORT under Windows, type
     make -fmakefile.win
If you want to run OORT under DOS, type
     make -fmakefile.dos

If the OORT makefile had to be edited in Step 1, then the
makefile in this directory must be edited as well.  See the
description of how to edit the OORT makefiles above.

After successfully building the Utilities library, you
should have a file called UTILS.LIB in the LIB directory.
You can now build and run examples.

3) Build an OORT application that links against the library.

IF YOU ARE RUNNING OORT UNDER WINDOWS:

Use the Windows-hosted Borland C++ IDE to open the project
(.PRJ) file for the example you would like to build (Select
"Open..." from the Project menu).  To build the program,
select "Make..." from the Compile menu.

After building the application, you can run it by choosing
"Run" from the Run menu.  You can modify the command-line
arguments to the program by selecting "Arguments..." from
the Run menu.  A complete list of command-line arguments is
given below.


You can also build the example from DOS or a DOS shell by
using Make. Type:

     make -fmakefile.win

Once the application is built, it can be run using the
Borland C++ IDE, as described above, or it can be invoked
from the "Run..." command in the File menu of the Program
Manager.

See the following section for information on what command-
line arguments are valid for the application.

IF YOU ARE RUNNING OORT UNDER DOS:

Use the Makefile in the example's directory to build the
program. Type:
     make -fmakefile.dos

Whether you are running under DOS or Windows, the result of
building an example program will be a very large (~800K-1M)
executable program (Most of this disk space is taken up by
debugging symbols, not code.)  This executable program takes
command-line parameters to determine the resolution of the
image to render, which part of the image to render, whether
to anti-alias the image, and other parameters.

4) Run the application.

The command-line parameters for an OORT application is as
follows.

Antialiasing options:
     -anti                    Antialias the image.
     -min[n]                  Minimum number of samples to
                              take for each pixel.  The
                              default is 4.
     -max[n]                  Maximum number of samples to
                              take for each pixel.  The
                              default is 16.
Rendering options:
     -e[end]                  Gives ending scanline.
                              Default is height.
     -h[height]               Gives height of the output
                              image.  Default is 200.
     -s[start]                Gives starting scanline.
                              Default is 0.
     -w[width]                Gives width of the output
                              image.  Default is 320.
Miscellaneous options:
     -S[filename]             Append statistics to the
                              given file.
     -o[filename]             Sends image to the given
                              file (default extension is
                              .RAW).


Example invocations:
     csgdemo -w1024 -h768
       Renders the CSGDEMO example at 1024x768 resolution.
          Not specifying an output file instructs the
          program to write to the default output file, which
          is given as CSGDEMO.RAW.

     csgdemo -anti -min8
       Invokes the CSGDEMO example.  Writes out a 320x200
          image (the default size).  The image is anti-
          aliased, with a minimum of 8 samples taken for
          each pixel.

     csgdemo -w1024 -h768 -s0 -e256 -ocsgdemo1
     csgdemo -w1024 -h768 -s256 -e512 -ocsgdemo2
     csgdemo -w1024 -h768 -s512 -e768 -ocsgdemo3
       These three command lines render the image at
          1024x768 resolution in three segments.  They can
          be invoked on separate computers to split the work
          three ways.  The resulting output files,
          CSGDEMO1.RAW, CSGDEMO2.RAW, and CSGDEMO3.RAW can
          be spliced into a single file with the Splice
          program, as follows:

              splice csgdemo1 csgdemo2 csgdemo3 -ocsgdemo

         This results in a single file CSGDEMO.RAW that can
          be quantized with RAW2GIF and displayed using a
          GIF viewer.

5) Run RAW2GIF on the resulting .RAW file.

     Color quantization is the process of choosing a limited
number of colors to represent a full-color image.  There are
several reasons to perform color quantization on an image.
One is compression: if you quantize a 24-bit image to an
image with less precision, you get a corresponding decrease
in size.  The primary reason to quantize an image, however,
is for display.
     Many computers, including most PC compatibles with VGA
and SuperVGA, are limited to displaying 256 or fewer colors
at once.  For such computers, images must be quantized
before they can be displayed.  RAW2GIF takes an output file
from the ray tracer, quantizes the image, and writes out a
file using the Graphics Interchange Format (GIF).
     GIF is a proprietary image file format used by
CompuServe that has many advantages for our application.
Many public domain or shareware programs can read and
display GIF images, so displaying our output images is not a
problem.  Also, GIF has built-in LZW compression and ray-
traced images tend to be very compressible.  The GIF file
resulting from a call to RAW2GIF is often an order of
magnitude smaller than the original RAW file.
     RAW2GIF uses the popular median-cut quantization
algorithm as described by Heckbert in SIGGRAPH '82, p. 297.
The command-line options are as follows.

Command-Line Options
  -[num]    Specify the number of colors to quantize to.
            This number must be a power of 2 in the range 2-
            256.
  -d        Perform Floyd-Steinberg dithering on the image.
            Turning this option on will significantly
            increase the time required to write the image,
            but it may reduce objectionable artifacts in
            the image due to aliasing.  Dithering can also
            increase the memory requirements.
  -i[file]  Specify an input file.  The default extension
            is .RAW.
  -o[file]  Specify an output file.  The default extension
            is .GIF.

Example invocations:

     raw2gif balls
          Quantizes balls.RAW to 256 colors (no dithering)
          and writes the resulting image out to balls.GIF.
     raw2gif -d -16 specular
          Quantizes specular.RAW to 16 colors with
          dithering, and writes the resulting image out to
          specular.GIF.
     raw2gif -ispecular. -ospheres.gif
          Takes as input the file "specular" (no extension),
          quantizes it to 256 colors without dithering and
          writes the resulting image out to spheres.GIF.

6) Look at the quantized image using any GIF viewer.

If you don't have one, there are dozens of public domain and
shareware ones.  Check your local bulletin board or
information service.  If you can't find one, email me and
I'll send you a copy of a shareware GIF viewer for DOS.