README for rsrt v7.61
by Alex Kourakos

   This is the first distribution of RSRT, the Really Simple Ray Tracer,
the only ray-tracer (that I've seen!) that will run with any success on
an Apple IIgs.

   Please note that this has not been fully optimized for running on a
16-bit Apple IIgs, but it still is not that slow. Waiting overnight for
a decent picture is acceptable at this stage. It is fine tuned for running
on 32-bit computers, but that will change...

-----
what is rsrt?
-----

   rsrt is a shell utility (w/ ORCA shell or something like that) that reads
a scene description file (see below) and generates a 24-bit image file
corresponding to that description using the ray-tracing method. If you don't
know what that is or how to use it, read on...

   I've been working on this for a few months, so a good many features have
not been implemented, but here is a run-down:

   two kinds of lights - directional and point source
   three object primitives - spheres, planes, discs

   diffuse & specular illumination
   specular reflection ("mirrored")
   no transparent objects (I'm working on it!)

   does shadows, has shadow cache for improved speed

   rudimentary 4-sample per pixel anti-aliasing

   minimal memory usage (usually < 10K)

   light intensities, and most surface features fully programmable

-----
how to use rsrt
-----

   First, you need a scene desription file. This file can be created in a
text editor. (see included example files). The format is similar to that of
the public-domain raytracer rayshade, by Craig Kolb. I've included just a
couple scene files that you should probably look at right now.

   This input file contains tokens and parameters that tell rsrt how to
create the scene. Most tokens have default values that wil be used if that
token is omitted. Note that RGB color values are real numbers between 0 and 1,
with 0 representing no intensity and 1 full intensity.
   Anywere in the file you can use "/*" and "*/" for comments, just like in C.

   To generate the image file, type "rsrt filename." rsrt will then read
through the file and do what it says to do. Simple.

-----
misc tokens
-----

outfile <string>  - saves image to the filename <string>. If this token is
                    not included in the file, the filename "rsrt.out" will
                    be used by default.

report <number>   - prints progress information every <number> scanlines. The
                    progress info in this version of rsrt is just a message
                    saying which line was finished. A value of 0 will make
                    rsrt keep quite. The default value is every 20 scanlines.

screen <xsize> [<ysize>] - sets the size of the image to xsize by ysize. If only
                    one number is given, the image is a square of that size.
                    The default is 128x128. Note: you don't want to make it
                    that big at first! Something like 20x20 would be better,
                    because it usually takes several hours for anything
                    really large.

window <xmin> <xmax> <ymin> <ymax> - render only the portion of the screen
                    bounded by these values. The default, of course, is
                    the whole screen.

gamma <gamm>      - gamma correct the image for display on a monitor with the
                    given gamma. You shouldn't really change this, because
                    any value other than 1.0 slows the program down.

maxdepth <depth>  - prune the ray tree after <depth> rays have been spawned.
                    The default is 7 rays. This value controls how "deep"
                    reflections go.

background <r> <g> <b> - set background color (color seen when no objects
                    are hit) to the red green blue values given. The default
                    is black (0,0,0).

-----
viewing information
-----

eyep <x> <y> <z>  - place the eye at the space point (x,y,z). Defaults to
                    (0,0,0).

lookp <x> <y> <z> - the space point the eye "looks at." The default is
                    (0,0,10).

up <x> <y> <z>    - the up direction. The default is (0,1,0).

fov <hfov> [<vfov>] - set the field of view in degrees. The field of view is
                    measured from the center of the viewplane to an edge.
                    The default is 45 degrees in the horizontal and vertical
                    directions. You can supply a negative value to flip the
                    image over.

-----
lights
-----

noshadow          - if this token is included in the input file, no shadows
                    will be tested for. This speeds up the ray-tracing process.

   When defining lights, <intens> may be an RGB color triple, one number
representing the intensity of white, or the number may be omitted to create
a bright white light.

light [<intens>] ambient - set ambient light. default is (1,1,1).

light [<intens>] directional <x> <y> <z> - create a directional (infinitely
                    far away) light that is always in the direction of (x,y,z).

light [<intens>] point <x> <y> <z> - create a point light source located at
                    (x,y,z).

   If you don't create any lights (besides the ambient) rsrt will make a
default one for you.

-----
objects
-----

   Object definitions are a little more complicated. The general form is

<objname> [<surface specification>] <obj parameters>

where the surface specification is optional. If the surface specification
is not given, the current surface is used.

   First, here are the object primitives currently supported by rsrt:

sphere <r> <x> <y> <z> - create a sphere of radius <r> with center at (x,y,z).

plane <x> <y> <z> <nx> <ny> <nz> - create a plane which contains the point
                    (x,y,z) and has a surface normal (nx,ny,nz).

disc <r> <x> <y> <z> <nx> <ny> <nz> - create a flat disc with radius r
                    containing the point (x,y,z) and having the surface
                    normal (nx,ny,nz).

-----
surfaces
-----

   Surface specifications usually go along with object definitions (see
above). There is a current surface that is applied to any object that doesn't
have a surface defined with it. That surface starts out as a plain, white,
non-reflective plastic-looking surface.

   A surface specification is one or more of the following. Any that aren't
given are defaulted to zero.

   ambient <r> <g> <b>  - set ambient reflectivity to (r,g,b).
   diffuse <r> <g> <b>  - set diffuse reflectivity to (r,g,b).
   specular <r> <g> <b> - set specular reflectivity to (r,g,b).
   specpow <exp>        - set specular exponent to <exp>. This controls how
                          sharp a highlight is on an object.
   reflect <r> <g> <b>  - reflectivity of surface. If this is (0,0,0), the
                          surface will not be reflective.

   To change the default surface (that which is applied to objects that
don't have explicit surfaces bound to them), you can use the following:

   applysurf <surface specification>

   From then on, the given surface is used.


   For a better understanding, see the example files that were included with
rsrt.
   Note that there is a certain degree of flexibility in the input file. If
you give bogus values, usually (not always!) rsrt will catch them and warn
you. If you define the same thing more than once, rsrt will use the last one.
The input file can be laid out in almost any way, with any whitespace for
seperation.

-----
image output
-----

   At this time, rsrt outputs images as 24-bit files, arranged like this:

unsigned long xsize,
unsigned long ysize,
the pixel data arranged as R,G,B bytes

   I have included a cheesy viewing program, called 'show24' that will display
these files as grayscale. Just type 'show24 filename' and the image will
be displayed in 16-level gray scale. This is not very good, though. If anyone
has any suggestions or source code for a good quantizer, I would love to hear
from you. I want to create 3200-color pictures on my GS with rsrt!! I've
created pictures on 24-bit graphics workstations and they look great. I just
wish I had the time to write a quantizer.

-----
etc
-----

   Well, I hope you enjoy rsrt. It is in its early stages right now, and I
will add lots more features soon (such as object transformations and
transparent surfaces). I wrote rsrt in a very modular way, so adding new
lights and objects takes no time at all. Stay tuned...I tend to put a lot
of effort in writing small, fast, efficient programs that will run on ANY
machine with a C compiler. I've compiled rsrt on everything from an IBM AT
to a Cray Y-MP without a hitch.

   I want to hear from anyone who has read this README. If you have any
suggestions about what I should do next with rsrt, or if you have any
criticisms or compliments, or if you downloaded it and don't know what the
hell it is, or if you want new versions as I write them, or if you have
questions about the source code, drop me some mail. My address on Internet
is:

   kourakos@ncsc.org

   and on proline, it's

   awk@pro-charlotte.cts.com


I want to hear from anyone who has any suggestions or has created interesting
pictures!! I especially would love it if someone would convert a picture to
3200 color for me...

Alex Kourakos