v21i015: A ray tracing program, Part08/08

[Rich Salz]

Submitted-by: Craig Kolb <craig at weedeater.math.yale.edu>
Posting-number: Volume 21, Issue 15
Archive-name: rayshade/part08

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#		"End of archive 8 (of 8)."
# Contents:  doc/rayshade.1
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/rayshade.1' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'doc/rayshade.1'\"
else
echo shar: Extracting \"'doc/rayshade.1'\" \(35763 characters\)
sed "s/^X//" >'doc/rayshade.1' <<'END_OF_FILE'
X.\" Manual page for rayshade, 'troff -man' format.
X.\"
X.\" $Id: rayshade.1,v 3.0 89/10/27 16:55:22 craig Exp $
X.\"
X.\" $Log:	rayshade.1,v $
X.\" Revision 3.0  89/10/27  16:55:22  craig
X.\" Baseline for first official release.
X.\" 
X.\" Updated by C. Kolb  7/1/88 12/21/88 6/8/89 9/11/89 10/6/89 10/16/89
X.\" Initial version May 12, 1988 Craig Kolb
X.TH RAYSHADE  1G "September 11, 1989"
X.UC 4
X.SH NAME
Xrayshade \- a raytracing program
X.SH SYNOPSIS
X.B rayshade
X[
X.I options
X] [
X.I filename
X]
X.SH DESCRIPTION
X.I Rayshade
Xreads a file describing a scene to be rendered and produces a
XUtah Raster RLE format file of the raytraced image.
X.br
X.SH OPTIONS
X.TP
X.B \-C \fIred_contrast green_contrast blue_contrast\fR
XSet contrast factors used in controlling pixel subdivision.
X.TP
X.B \-c
XTrace shadow rays through transparent objects.
X.TP
X.B \-E \fIeye_separation\fR
XSet eye separation for stereo imaging.
X.TP
X.B \-h
XPrint a short usage message.
X.TP
X.B \-j
XPerform jittered sampling.
X.TP
X.B \-L \fIstart_line\fR
XBegin trace on line \fIstart_line\fR, appending to image file (requires
X\fB-O\fR option).
X.TP
X.B \-l
XRender image for left eye (requires \fB-E\fR option).
X.TP
X.B \-n
XDo not trace shadow rays.
X.TP
X.B \-O \fIoutput_file\fR
XOverride image file name in input file, if any.
X.TP
X\fB\-P\fI pixel_subdivisions\fR
XSpecifies the maximum number of times a pixel may be subdivided.
X.TP
X.B \-p
XDiscard polygons with degenerate edges.
X.TP
X.B \-q
XDo not print warning messages.
X.TP
X.B \-R \fIxres yres\fR
XSet image resolution.
X.TP
X.B \-r
XRender image for right eye (requires \fB-E\fR option).
X.TP
X.B \-S \fIsamples\fR
XSpecifies number of jittered samples.
X.TP
X.B \-s
XDo not cache shadowing information.
X.TP
X.B \-T \fIthresh\fR
XSpecifies adaptive ray-depth cutoff threshold.
X.TP
X.B \-V \fIfilename\fR
XWrite verbose output to \fIfilename\fR.
X.TP
X.B \-v
XWrite verbose output to standard output.
X.TP
X.B \-W \fIworkers\fR
XSpecify number of worker processes (Linda implementation only).
X.br
X.SH OVERVIEW
X.PP
X.I Rayshade
Xis an raytracer capable of raytracing images of objects composed
Xof a large number of primitive objects.
X.I Rayhade
Xreads a series of lines supplied on the standard input or contained
Xin the file named on the command line.
XAfter reading the input file,
X.I rayshade
Xraytraces the image from
Xthe bottom upwards.  As each scanline is traced, pixels are written to
Xa Utah Raster RLE format image file.  By default, this image file is written
Xto the standard output, and
Xinformation messages and statistics
Xare written to the standard error.
X.br
X.SH "INPUT FILE FORMAT"
X.PP
XThe input file consists of commands (denoted by keywords) followed by
Xnumerical
Xor character
Xarguments.
XSpaces, tabs, or newlines may be used to separate items in the file.
XCoordinates and
Xvectors are specified in arbitrary floating-point units, and may be
Xwritten with or without a decimal point.
XColors are specified as
Xred-green-blue floating-point triplets which indicate intensity
Xand range from 0
X(zero intensity) to 1. (full intensity).
X.PP
XA
X.B #include
Xdirective is supported which, as in the C language,
Xcauses the contents of the quoted filename which follows to be read and
Xeffectively inserted at that point in the input file.  Be warned that
X.I rayshade
Xdoes no checking for mutual or recursive inclusion of files.
X.PP
XThe following sections describe the keywords which may be included
Xin the input file.  Items in boldface type are literals, while 
Xsquare brackets surround optional items.
X.br
X
X.SH "VIEWING PARAMETERS"
X.TP
X\fBeyep\fI x y z\fR
XSpecifies the eye's position in space.  The default is (0, 20, 0).
X.TP
X\fBlookp\fI x y z\fR
XSpecifies the point at which the eye is looking.  The default is (0, 0, 0).
X.TP
X\fBup\fI x y z\fR
XSpecifies the direction which should be considered
X"up" from the eye's position.  Note that
Xthis vector need not be perpendicular to the vector between the look point
Xand the eye's position.  The default is (0, 0, 1.).
X.TP
X\fBfov\fI horizontal_field_of_view \fR[\fIvertical_field_of_view\fR]
XThe horizontal field of view specifies the angle, in degrees,
Xbetween the left-most and right-most
Xcolumns of pixels 
XIf present, the vertical
Xfield of view specifies the angle between
Xthe center of the top-most and bottom-most row of pixels.
XIf not present, the vertical field of view
Xis calculated using the screen resolution and the assumption that pixels are
Xsquare.
XThe default horizontal field-of-view is 45 degrees, while the default vertical
Xfield-of-view
Xis calculated as described above.
X.br
X.SH "IMAGE GENERATION"
XWhen specified in the input file, many of the image-generation commands
Xmay be overridden through command-line options.  For example, the line
X"screen 1024 768" in an input file may be overridden by specifying
X"-R 128 128" on the command line.
X.TP
X\fBscreen \fIx_resolution y_resolution\fR
XSpecifies the horizontal and vertical resolution of the image to be traced.
XThis command may be overridden through use of
Xthe \fB-R\fR option.
XThe default resolution
Xis 512 by 512 pixels.
X.TP
X\fBbackground \fIred green blue\fR
XSpecifies the color that should be assigned to rays
Xwhich do not strike any object in the scene.
XThe default is black (0, 0, 0).
X.TP
X\fBoutfile \fIfilename\fR
XSpecifies the name of the file to which the resulting image should be
Xwritten.
XBy default, the image is written to the standard output.
XThis command may be overridden through the use of the \fB-O\fR option.
X.TP
X\fBmaxdepth \fImaximum_depth\fR
XControls the maximum depth of the ray tree.  The default is 3, with eye
Xrays considered to be of depth zero.
X.TP
X\fBcutoff \fIcutoff_threshold\fR
XSpecifies the adaptive ray-depth cutoff threshold.  When any ray's maximum
Xcontribution
Xto the final color of a pixel falls below this value, the ray and its children
X(specularly transmitted and reflected rays) are not spawned.
XThis threshold may be overridden through
Xthe use of the
X\fB-T\fR option.  The default value is 0.001.
X.TP
X\fBjittered\fR
XUse "jittered" sampling.  This command may be overridden through the use
Xof the \fB-P\fR option.  The default is to use adaptive supersampling.
X.TP
X\fBadaptive \fImax_divisions\fR
XSpecifies that adaptive supersampling should be used, and that each pixel
Xmay be subdivided at most \fImax_divisions\fR times.
XThis command may be overridden through the use of the \fB-j\fR
Xor \fB-P\fR options.
XThe default value is one.
X.TP
X\fBsamples \fInum_samples\fR
XSpecifies the number of jittered samples.  See SAMPLING for details.
XWhen specified, this value may be overridden through the use of the
X\fB-S\fR option.  The default value is three.
X.TP
X\fBcontrast \fIred green blue\fR
XSpecifies the maximum allowed contrast between samples in a (sub)pixel
Xbefore subdivision takes place.  See SAMPLING for details.
XWhen specified in the input file, these
Xvalues may be overridden through the use of the \fB-C\fR option.  The
Xdefaults for the red, green and blue channels are 0.25, 0.2, and 0.4,
Xrespectively.
X.SH "LIGHT SOURCES"
X.PP
XThree types of light sources are supported:  point, extended (area), and
Xdirectional.
XPoint sources are specified by a location in world-space
Xand produce shadows with sharp edges.  Extended sources are specified
Xby a location and a radius.  They produce shadows with "fuzzy" edges
X(penumbrae), but increase ray-tracing time considerably.  Directional
Xsources are specified by a direction.
XA maximum of 10 light sources may be defined.
X.PP
XIn the definitions below,
X.I brightness
Xspecifies the intensity of the light source.  If a
Xsingle floating-point number is given, the light source emits a "white" light
Xof the indicated normalized intensity.  If three floating-point numbers
Xare given, they are interpreted as the normalized red, green and blue
Xcomponents of the light source's color.
X.PP
XLights are defined as follows:
X.TP
X\fBlight \fIbrightness \fBpoint\fI x y z\fR
XCreates a point source located at (
X.I x, y, z
X).
X.TP
X\fBlight \fIbrightness \fBextended\fI x y z radius\fR
XCreates an extended source centered at
X(
X.I x, y, z
X)
Xwith the indicated \fIradius\fR.  The images produced using extended sources
Xare usually superior to those produced using point sources, but ray-tracing
Xtime is increased substantially.  Rather than tracing one shadow
Xray to a light source, multiple rays
Xare traced to various points on the extended source.  The extended source
Xis approximated by sampling a square grid light sources.
XSee SAMPLING for more details on the
Xsampling of extended light sources.
X.TP
X\fBlight \fIbrightness \fBdirectional\fI x y z\fR
XCreates a directional
Xlight source whose direction vector from each point
Xin world space is defined as
X(
X.I x, y, z
X).  This vector need not be normalized.
X.br
X.SH SURFACES
X.PP
XEvery primitive object has a surface associated with it.  The surface specifies 
Xthe color, reflectivity, and transparency of an object, and may be
Xdefined anywhere in the input file as long as it is defined before it
Xis used.
XSurfaces are
Xdefined once, and may be associated with any number of primitive objects.
XA surface definition is given by:
X.TP
X\fBsurface \fIsurf_name ar ag ab dr dg db sr sg sb coef refl transp index \fR[\fItranslu stcoef\fR]
X.PP
X.I Surf_name
Xis the name associated with
Xthe surface.  This name must be unique for each surface.
X.PP
X.I Ar, ag
Xand
X.I ab
Xare used to specify the red, green, and blue components of the surface's
Xambient color.  This color is always applied to a ray striking the surface.
X.PP
X.I Dr, dg
Xand
X.I db
Xspecify the diffuse color of the surface.  This color, the
X.I brightness
Xcomponent of each light source whose light strikes the surface, and
Xdot product of the incoming ray and the surface normal at the point of
Xintersection
Xdetermine the color which is added to the color of the ray striking
Xthe surface.
X.PP
X.I Sr, sg
Xand
X.I sb
Xare used to specify the specular color of the surface.  The application of
Xthis color is controlled by the
X.I coef
Xparameter, a floating-point number which indicates the power to which the
Xdot product of the surface's normal vector at the point of intersection
Xand the vector to each light source should be raised.  This number is
Xthen used to scale the specular color of the surface, which is then added
Xto the color of the ray striking the surface.
XThis model (Phong lighting) simulates specular
Xreflections of light sources on the surface of the object.
XThe larger
X.I coef
Xis, the smaller highlights will be.
X.PP
X.I Refl
Xis a floating-point number between 0 and 1 which indicates the reflectivity
Xof the object.  If non-zero, a ray striking the surface will spawn
Xa reflection ray. The color assigned to that ray will be scaled
Xby
X.I refl
Xand added to the color of the surface.
X.PP
X.I Transp
Xis
Xa floating-point number between 0 and 1
Xwhich indicates the transparency of the object.  If non-zero,
Xa ray striking the surface will spawn a ray which is transmitted through
Xthe object,
Xand the resulting color of this ray is scaled by
X.I transp
Xand added to
Xthe color of the surface.  The direction of the refraction
Xray is controlled by the
X.I index
Xparameter, which indicates the index of refraction of
Xthe surface.
X.PP
XThe optional parameters \fItranslu\fR and \fIstcoef\fR may be used
Xto give a surface a translucent appearance.  \fITranslu\fR is the
Xtranslucency of the surface.   If non-zero and a light source
Xilluminates the side of the surface opposite that being rendered,
Xdiffuse lighting calculations are performed with respect to
Xthe side of the surface facing the light,
Xand
Xthe result is 
Xscaled by \fItranslu\fR and added to the color of the incident ray.
XThus, \fItranslu\fR accounts for diffuse transmission of light
Xthrough the primitive.
X\fIStcoef\fR is similar to \fIcoef\fR, but it applies to the specular
Xtransmission of highlights.  Note that in both cases the index
Xof refraction of the surface is ignored.  By default, surfaces
Xhave zero translucency.
X.br
X.SH PRIMITIVES
X.PP
XThe raytracer is capable of rendering a number of primitive objects.
XPrimitives may be specified inside of an object-definition block, in
Xwhich case it is added to the list of primitives belonging to that
Xobject. In addition, primitives may be defined
Xoutside of object-definition blocks.  Primitives such as these are
Xadded to the list of primitives belonging to the World object.  See
Xbelow for more details.
X.PP
XRayshade usually ensures that a primitive's normal is pointing
Xtowards the origin of the incident ray when performing shading calculations.
XExceptions
Xto this rule are transparent primitives, for which rayshade uses the
Xdot product of the normal and the incident ray to determine if the ray
Xis entering or exiting the surface, and superquadrics, whose normals
Xare never modified due to the nature of the ray/superquadric interesection
Xcode.  Thus, all non-transparent primitives except superquadrics will in
Xeffect be double-sided.
X.PP
XPrimitives are specified by lines of the form:
X.TP
X.I
Xprimitive_type surface <primitive definition>
X.in +16
X[\fItransformations\fR] [\fItexture mapping information\fR]
X.in -16
X.br
X\fISurface\fR is the name of the surface to be associated with the
Xprimitive.
XTexture mapping and transformations are
Xdiscussed below.  A list of available primitives
Xfollows.
X.br
X.TP
X\fBsphere \fIsurface radius xcenter ycenter zcenter\fB
XCreates a sphere with the indicated
X.I radius
Xcentered at (
X.I xcenter, ycenter, zcenter
X).
X.TP
X\fBtriangle \fIsurface x1 y1 z1 x2 y2 z2 x3 y3 z3\fR
XCreates a triangle with vertices (
X.I x1, y1, z1
X), (
X.I x2, y2, z2
X) and (
X.I x3, y3, z3
X).  Vertices should be given in a counter-clockwise order as one is
Xlooking at the 'top' face of the triangle.
X.TP
X\fBtriangle \fIsurface p1x p1y p1z n1x n1y n1z  p2x p2y p2z n2x n2y n2z\fR
X.in +16
X\fIp3x p3y p3z n3x n3y n3z\fR
X.in -16
XDefines a Phong-shaded triangle.  Here, the first three floating-point numbers
Xspecify the first vertex, the second three specify the
Xnormal at that vertex, and so on.  Again, vertices should be
Xspecified in counter-clockwise order.
XCurrently, all three vertex/normal pairs
Xare stored for every triangle (as opposed to storing pointers to these
Xvectors, which would reduce storage space in cases where more than one
Xtriangle shared a vertex).
X.TP
X\fBpoly \fIsurface x1 y1 z1 x2 y2 z2 x3 y3 z3 \fR[\fIx4 y4 z4 ...\fR]
XCreates a polygon with the specified vertices.  The vertices should be given in
Xa counter-clockwise order as one faces the "top" of the polygon.
XThe polygon may be non-convex,
Xbut non-planar polygons will not be rendered correctly.  The number of vertices
Xdefining a polygon is limited only by available memory.
X.TP
X\fBplane \fIsurface xnormal ynormal znormal x y z\fR
XCreates a plane which passes through the point (
X.I x, y, z
X) and has normal (
X.I xnormal, ynormal, znormal
X).
X.TP
X\fBcylinder \fIsurface xbase ybase zbase xtop ytop ztop radius\fR
XCreates a cylinder which extends from (\fIxbase\fR, \fIybase\fR, \fIzbase\fR)
Xto (\fIxtop\fR, \fIytop\fR, \fIztop\fR) and has the indicated \fIradius\fR.
X.TP
X\fBcone \fIsurface xbase yase zbase xtop ytop ztop base_radius top_radius\fR
XCreates a (truncated)
Xcone which extends from (xbase, ybase, zbase) to (xtop, ytop, ztop).
XThe bottom of the cone will have radius
X.I base_radius,
Xwhile the top will have radius
X.I top_radius.
X.TP
X\fBheightfield \fIfilename\fR
XReads height field data from \fIfilename\fR and creates a height square
Xheight field of unit size centered at (0.5, 0.5).  The binary data in
X\fIfilename\fR
Xis stored as an initial integer giving the square root of number of data
Xpoints in the file, followed by the data stored as floating-point
Xnumbers.  The height field is rendered as a surface tessellated by triangles.
XNon-square height fields may be rendered by setting vertex heights to
Xless than or equal to -1000.  Triangles which have all vertices less than
Xor equal in altitude to this value are not rendered.
X.TP
X\fBbox \fIsurface xcenter ycenter zcenter xsize ysize zsize\fR
XCreates a box centered at (
X.I xcenter, ycenter, zcenter
X) of size
X(2 *
X.I xsize,
X2 *
X.I ysize,
X2 *
X.I zsize
X).  Although boxes must initially be aligned with the world axes,
Xthey may be transformed at will.
X.br
X.TP
X\fBsuperq \fIsurface xcenter ycenter zcenter xsize ysize zsize power\fR
XCreates a superquadric with center (
X.I xcenter, ycenter, zcenter,
X) of total
Xsize (2 *
X.I xsize,
X2 *
X.I ysize,
X2 *
X.I zsize,
X).
X.I Power
Xdefines
Xhow closely the superquadric resembles the corresponding box.  The larger
Xthe value of
X.I power,
Xthe closer it will resemble the box (with rounded corners).  A value greater
Xthan or equal to one is required for reasonable images.  In addition,
Xneither transparent superquadrics nor superquadrics viewed from the
Xinterior will rendered correctly.
X.br
X.SH OBJECTS
X.PP
XOne key feature of
X.I rayshade
Xis its ability to treat groups of primitives as objects which may 
Xtransformed and instantiated at will.
XObjects are composed of groups of primitives and/or other objects and
Xare specified in the input file as:
X.nf
X
X	\fBdefine\fI object_name\fR
X		[\fBgrid\fI xvoxels yvoxels zvoxels\fR]
X		[\fBlist\fR]
X		[primitives]
X		[instances]
X	\fBdefend\fR [texturing information]
X
X.fi
XThe ordering of the various elements inside the object-definition block
Xis inconsequential.
XHere, [\fIinstances\fR]
Xare any number of declarations of the form:
X.TP
X\fBobject \fIobject_name \fR[\fItransformations\fR] [\fItexturing information\fR]
XThis causes a copy of the named object to be made, transformed and textured as
Xrequested, and added to the object being defined.
XAn object must be defined before it may be
Xinstantiated, which ensures that no cycles appear in the object-definition
Xgraph.
X.PP
XA special object named
X.I World
Xis maintained internally by 
X.I rayshade.
XPrimitive definitions and object instantiations which do not appear
Xinside an object-definition block are added to this object.  When
Xperforming raytracing, rays are intersected with the objects that make up
Xthe World object.
X.PP
XInternally, objects are stored by one of two means.  By default,
Xgroups of primitives which make up an object are stored in a \fIlist\fR.
XThe constituents of such an object are stored in a simple
Xlinked-list.  When a ray is intersected with such an object, the ray
Xis tested for intersection with each object in the list.
XWhile the \fIlist\fR is the default method of object storage, one may
Xemphasize this fact in the input file by including the
X.B list
Xkeyword somewhere within the object-definition block.
X.PP
XThe second form of internal object storage is the three-dimensional \fIgrid\fR.
XThe grid's total size
Xis calculated by
X.I rayshade
Xand is equal to the bounding box of the entire object.
XA grid subdivides the space in which an object lies into an array
Xof uniform box-shaped
X.I voxels.
XEach voxel contains a linked-list of objects and primitives which
Xlie within that voxel.  When intersecting a ray with an object whose
Xconstituents are stored in a grid, the ray is traced incrementally from
Xvoxel-to-voxel, and the ray is intersected with each object in the
Xlinked list of each voxel that is visited.
XIn this way
Xthe intersection of a ray with a collection of objects is
Xgenerally made faster at the expense of increased storage
Xrequirements.
X.PP
XThis form of object representation is enabled by including the
Xthe
X.B grid
Xkeyword somewhere within the object-definition block:
X.TP
X\fBgrid \fIxvoxels yvoxels zvoxels\fR
XStores the object being defined as a grid consisting of
Xa total of (xvoxels * yvoxels * zvoxels) voxels, with
X.I xvoxels
Xalong the x-axis of the grid,
X.I yvoxels
Xalong the y-axis,
Xand
X.I zvoxels
Xalong the z-axis.  For reasonably complex objects, a value of 20 for each
Xparameter usually works well.
X.PP
XFor convenience, one may also define surfaces inside of an object-definition
Xblock.  Surfaces defined in this manner are nevertheless globally available.
X.PP
XIn addition, object definitions may be nested.  This facilitates the
Xdefinition of objects through the use of recursive programs.
X.br
X.SH TRANSFORMATIONS
X\fIRayshade\fR allows for the application of arbitrary linear transformations
Xto primitives and compound objects.
XThe specification of transformations
Xoccurs immediately following the specification of a primitive or
Xinstantiation of an object.
XAny number of transformations may be composed; the resulting total
Xtransformation is applied to the entity being transformed.  Transformations
Xare specified by:
X.TP
X\fBtranslate \fIx y z\fR
XTranslate the object by (
X.IR "x, y, z" ).
X.TP
X\fBrotate \fIx y z theta\fR
XRotate the object counter-clockwise about the vector (
X.I x, y, z
X) by
X.I theta
Xdegrees.
X.TP
X\fBscale \fIx y z\fR
XScale the object by (
X.I x, y z
X).
X.TP
X\fBtransform \fIx1 y1 z1 x2 y2 z2 x3 y3 z3\fR
XTransform the object by the column-major matrix specified by the nine
Xfloating-point numbers.
XThus, a point (x, y, z) on the surface of the object
Xis mapped to (x*x1 + y*y1 + z*z1, x*x2 + y*y2 + z*z2, x*x3 + y*y3 + z*z3).
X.br
X.SH "TEXTURE MAPPING"
X.PP
X.I Rayshade
Xprovides a means of applying solid procedural textures to surfaces of
Xprimitives.  This is accomplished by supplying texture mapping information
Ximmediately following the definition of a primitive, object, or instance
Xof an object.  This allows one to texture individual primitives,
Xobjects, and individual instances of objects at will.
XTexturing information is supplied via a number of lines
Xof the following form:
X.TP
X\fBtexture\fR \fItexture_type\fR [\fIarguments\fR] [\fItransformations\fR]
X.br
X.I Texture_type
Xis the name of the texture to apply.
X.I Arguments
Xare any arguments that the specific texture type requires.
XIf supplied, the indicated
X.I transformations
Xwill be applied to the texture.  (More accurately, the inverse of
Xthe supplied transformation is applied to the point of intersection
Xbefore it is passed to the texturing routines.)
X.PP
XVersions of Perlin's Noise() and DNoise()
Xfunctions are used to generate values for
Xmost of the interesting textures.
XCurrently, there are seven textures available:
X.TP
X\fBbump\fI scale\fR
Xapplies a random bump map to the surface being textured.  The point of
Xintersection is passed to DNoise().  The returned normalized vector,
Xweighted by
X.I scale
Xis added to the normal vector at the point of intersection.
X.TP
X\fBchecker\fI size surface\fR
Xapplies a (3D) checkerboard texture to the object being textured.  Every
Xpoint that falls within an "even" cube will be shaded using the characteristics
Xof the named surface.  Every point that falls within an "odd" cube will
Xretain its usual surface characteristics.  Be warned that strange effects
Xdue to roundoff error are possible when the planar surface of an object lies
Xin a plane of constant integral values in texture space.
X.TP
X\fBblotch \fIblend_factor surface\fR
XThis texture produces a mildly interesting blotchy-looking surface.
X.I Blend_factor
Xis used to control the interpolation between a point's default surface
Xcharacteristics and the characteristics of the named surface.  A value
Xof 0 results in a roughly 50-50 mix of the two surfaces.
XHigher values result in greater instances of the 'default' surface type.
X.TP
X\fBfbm \fIscale offset H lambda octaves thresh\fR [\fIcolormap\fR]
XThis texture generates a sample of discretized fractional Brownian motion (fBm)
Xand uses it to modify the diffuse component of an object's color.  If no
X\fIcolormap\fR is named, the sample
Xis used to scale the object's diffuse color.
XIf a \fIcolormap\fR name is
Xgiven, a 256-entry colormap is read from the named file, and the object
Xis colored using the values in this colormap (see below).
X\fIScale\fR is used to scale the output
Xof the fractional Brownian motion function.  \fIOffset\fR  allows one
Xto control the
Xminimum value of the fBm function.  \fIH\fR is related to the
X\fIHolder constant\fR
Xused in the fBm (a value of 0.5 works well).  \fILambda\fR is
Xused to control the \fIlacunarity\fR, or spacing between successive
Xfrequencies, in the fBm (a value of 2.0 will suffice).  \fIOctaves\fR
Xspecifies the number of octaves of Noise() to use in simulating the fBm (5 to 7
Xworks well), and \fIthresh\fR is used to specify a lower bound on the
Xoutput of fBm function.  Any value lower than \fIthresh\fR is set to zero.
X.TP
X\fBfbmbump \fIscale offset H lambda octaves thresh\fR
XThis texture is similar to the \fBfBm\fR texture.  Rather modifying the
Xcolor of a surface, \fBfBmBump\fR acts as a bump map.
X.TP
X\fBmarble\fR [\fIcolormap\fR]
XThis texture gives a surface a marble-like appearance.  If the name of a
X\fIcolormap\fR file is given, the marble will be colored using the RGB values
Xin the colormap.  If no colormap name is given, the diffuse component of
Xthe object's surface is simply scaled.  One may transform the texture to
Xcontrol the density of the marble veins.
X.TP
X\fBwood\fR
X.br
XThis texture gives a wood-like appearance to a surface.
X.PP
XA colormap is an ASCII file
X256 lines in length, each line containing three space-separated integers
Xranging from 0 to 255.  The first number on the nth line specifies the red
Xcomponent of the nth entry in the colormap, the second number the green 
Xcomponent, and the third the blue.
X.PP
XIt is important to note that more than one texture may be applied to
Xa point at any time.  In addition to being able to apply more than
Xone texture directly (by supplying multiple "texturing information" lines for
Xa single object), one may instantiate textured objects which, in turn,
Xmay be textured or contain instances of objects which are textured, and so on.
X.br
X.SH "ATMOSPHERIC EFFECTS"
X.PP
X.I Rayshade
Xhas the capability of including several kinds of atmospheric effects
Xwhen rendering an image.  Currently, one such effect is available:
X.TP
X\fBfog\fI thinness red green blue\fR
XAdd global exponential fog with the specified \fIthinness\fR and color.
XFog is simulated by blending the color of the fog with the color of
Xeach ray.  The amount of fog color added to a ray is a function of
Xthe logarithm of the
Xdistance from the ray origin to the point of intersection divided by
X\fIthinness\fR.
X.br
X.SH "SAMPLING"
X.PP
XThis section clarifies how antialiasing and sampling of extended light
Xsources are accomplished.  Two types of anti-aliasing are supported;  adaptive
Xsubdivision and
Xso-called "jittered sampling".
X.PP
XAdaptive subdivision works by sampling each pixel at its corners.  The contrast
Xbetween these four samples is computed, and if too large, the pixel is
Xsubdivided into four equivalent sub-pixels and the process is repeated.
XThe threshold contrast may be controlled via the \fB-C\fR option or
Xthe \fBcontrast\fR command.
XThere are separate
Xthresholds for the red, green, and blue channels.  If the contrast
Xin any of the three is greater than the appropriate treshold value,
Xthe pixel is subdivided.
XThe pixel-subdivision process is repeated until either
Xthe samples' contrast is less than the threshold or the maximum pixel
Xsubdivision level, specified via the \fB-P\fR option or the \fBadaptive\fR
Xcommand, is reached.  When
Xthe subdivision process is complete, a weighted average of the samples
Xis taken as the color of the pixel.
X.PP
XJittered sampling works by dividing each pixel into a number of square
Xregions and tracing a ray through \fIsome\fR point in each region.  The
Xexact location in each region is chosen randomly.  The number of regions
Xinto which a pixel is subdivided is specified through the use of the
X\fB-S\fR option.  The integer following this option specifies the square
Xroot of the number of regions.
X.PP
XEach area light source is, in effect, approximated by a square grid
Xof light
Xsources.  The length of each side of the square is equal to the diameter
Xof the extended source.
XEach array element, which
Xis square in shape, is in turned sampled by randomly choosing a point
Xwithin that element to which a ray is traced from the point of
Xintersection.
XIf the ray does not intersect any primitive object before it
Xstrikes a light source element, there is said to be no shadow cast
Xby that portion of the light source.
XThe fraction of the light emitted by an
Xextended light source which reaches the point of
Xintersection is the number of elements
Xwhich are not blocked by
Xintervening objects divided by the total number of elements.  The
Xfraction is used to scale the intensity (color) of the light source, and this
Xscaled intensity is then
Xused in the various lighting calculations.
X.PP
XWhen jittered sampling is used, one shadow ray is traced to each
Xextended source per shading calculation.  The element to be sampled is
Xdetermined
Xby the region of the pixel through which the eye ray at the top of the
Xray tree passed.
X.PP
XWhen adaptive supersampling is used, the \fB-S\fR option or the
X\fBsamples\fR command controls how
Xmay shadow rays are traced to each extended extended light source
Xper shading calculation.
XSpecifically,
Xeach extended source is approximated by a square array consisting
Xof \fIsamples\fR * \fIsamples\fR elements.  However,
Xthe corners of the array are skipped to save rendering time and
Xto more closely approximate the circular projection of an extended light
Xsource.  Because the corners are
Xskipped,  \fIsamples\fR must be at least 3 if adaptive supersampling is
Xbeing used.
X.PP
XNot that the meaning of the \fB-S\fR option (and the \fBsamples\fR
Xcommand) is different depending upon
Xwhether or not jittered
Xsampling is being used.
X.PP
XWhile jittered sampling is generally
Xslower than adaptive subdivision, it can be beneficial if the penumbrae
Xcast by extended light sources take up a relatively large percentage
Xof the entire image or if the image is especially prone to aliasing.
X.SH EXAMPLES
XA very simple
X.I rayshade
Xinput file might be:
X.nf
X.IN +8
X
Xlight 1.0 directional 1. 1. 1.
X
Xsurface red  .2 0 0  .8 0 0  .5 .5 .5  32. 0.8 0. 1.
Xsurface green  0 .2 0  0 .8 0  0 0 0  0. 0. 0. 1.
X
Xsphere red 8.  0. 0. -2.
Xplane green 0. 0. 1.  0. 0. -10.
X
X.IN -8
X.fi
X.PP
XPassing this file to
X.I rayshade
Xwill result in an image of a red reflective sphere sitting on a white
Xground-plane being written to the standard output.  Note that in this case,
Xdefault values for
X.B
Xeyep, lookp, up, screen, fov,
Xand
X.B background
Xare assumed.
X.PP
XA more interesting example uses instantiation to place multiple copies
Xof an object at various locations in world space:
X.nf
X.IN +8
X
Xeyep 10. 10. 10.
Xfov 20
Xlight 1.0 directional 0. 1. 1.
Xsurface red  .2 0 0  .8 0 0  .5 .5 .5  32. 0.8 0. 1.
Xsurface green  0 .2 0  0 .8 0  0 0 0  0. 0. 0. 1.
Xsurface white 0.1 0.1 0.1 0.8 0.8 0.8 0.6 0.6 0.6 30 0 0 0
X
Xdefine blob
X	sphere red 0.5   .5 .5 0.
X	sphere white 0.5 .5 -.5 0. texture marble scale 0.5 0.5 0.5
X	sphere red 0.5  -.5 -.5 0.
X	sphere green 0.5 -.5 .5 0.
Xdefend
X
Xobject blob translate 1. 1. 0.
Xobject blob translate 1. -1. 0.
Xobject blob translate -1. -1. 0.
Xobject blob translate -1. 1. 0.
Xgrid 20 20 20
X
X.IN -8
X.fi
X.PP
XHere, an object named
X.I blob
Xis defined to consist of four spheres, two of which are red and reflective.
XThe object is stored as a simple list of the four spheres.
XThe
X.I World
Xobject consists of four instances of this object, translated to place
Xthem in a regular pattern about the origin.  Note that since the marbled
Xsphere was textured in "sphere space" each instance of that particular sphere
Xhas exactly the same marble texture applied to it.
X.PP
XOf course, just as the object 
X.I blob
Xwas instantiated as part of the
X.I World
Xobject, one may instantiate objects as part of any other object.  For
Xexample, a series of objects such as:
X.nf
X	define wheel
X		sphere tire_color 1.  0 0 0  scale 1. 0.2 1.
X		sphere hub_color 0.2 0 0. 0
X	defend
X
X	define axle
X		object wheel translate 0. 2. 0.
X		object wheel translate 0. -2. 0.
X		cylinder axle_color 0. -2. 0. 0. 2. 0. 0.1
X	defend
X
X	define truck
X		box truck_color 0. 0. 0. 5. 2. 2.	/* Trailer */
X		box truck_color 6. 0 -1 2 2 1		/* Cab */
X		object axle translate -4 0 -2
X		object axle translate 4. 0. -2.
X	defend
X
X.fi
Xcould be used to define a very primitive truck-like object.
X.br
X.SH "MINIMIZING RAYTRACING TIME"
X.PP
XRay tracing is a computationally intensive process, and rendering
Xcomplex scenes can take hours of CPU time, even on relatively powerful
Xmachines.  There are, however, a number of ways of attempting to reduce the
Xrunning time of the program.
X.PP
XThe first and most obvious way is to reduce the number of rays which
Xare traced.  This is most simply accomplished by reducing the resolution
Xof the image to be rendered.  The
X.B \-P
Xoption may be used to reduce the maximum pixel subdivision level.
XA maximum level of 0 will speed raytracing up considerably, but will result
Xin obvious aliasing in the image.  By default, a pixel will be subdivided
Xa maximum of one time, giving a maximum of nine rays per pixel total.
X.PP 
XAlternatively, the
X\fB-C\fR option or the \fBcontrast\fR command 
Xmay be used to decrease the number of instances in which
Xpixels are subdivided.  Using these options, one may indicate the maximum
Xnormalized contrast which is allowed before supersampling will occur.  If the
Xred, green or blue contrast between neighboring samples (taken at pixel corners)
Xis greater than the maximum allowed, the pixel will be subdivided into
Xfour sub-pixels and the sampling process will recurse until the sub-pixel
Xcontrast is acceptable or the maximum subdivision level
Xis reached.
X.PP
XThe number of rays traced can also be lowered by
Xmaking all surfaces non-reflecting and non-refracting or by
Xsetting
X.B maxdepth
Xto a small number.  If set to 0, no reflection or
Xrefraction rays will be traced. 
XLastly, removing all light sources
Xwill cause no shadow rays to be traced, but will result in a flat-looking
Ximage.
X.PP
XIn addition, judicious use of the \fBgrid\fR command can reduce rendering
Xtimes substantially.
XHowever, if an object consists of a relatively small number of simple objects,
Xit will likely take less time to simply check for intersection with
Xeach element of the object than to trace a ray through a grid.
X.br
X.SH FILES
X.nf
XExamples/*				example input files
X.fi
X.br
X.SH "AUTHORS"
X.I Rayshade
Xhad its beginnings as an
X"introductory" public-domain
Xraytracer written by Roman Kuchkuda.  Vestiges of his code may be found
Xin rayshade, particularly in the names of variables and the superquadric
Xcode.
XThe first version of
X.I rayshade
Xwas written at Princeton University during 1987-88
Xby Craig Kolb, David C. Hoffman, and David P. Dobkin.
XThe current manifestation of
X.I rayshade
Xwas written during the fall of 1988 by Craig Kolb.
XThe Noise() and DNoise() routines which form the basis of many
Xof the texturing functions were written by Robert Skinner and Ken
XMusgrave.
X.br
X.SH "CAVEATS"
X.PP
X.I Rayshade
Xperforms no automatic hierarchy construction.  The intelligent placement
Xof objects in grids and/or lists is entirely the job of the modeler.
X.PP
XWhile transparent objects may be wholly contained in other transparent
Xobjects, rendering partially intersecting transparent objects with
Xdifferent indices of refraction is, for the most part, nonsensical.
X.PP
X.I Rayshade
Xis capable of using large amounts of memory.  In the environment in
Xwhich it was developed (machines with at least 8 Megabytes
Xof physical memory plus virtual memory), this has not been a problem,
Xand scenes containing several billion primitives have been
Xrendered.  On smaller machines, however, memory size can be a limiting factor.
X.PP
XThe "Total memory allocated" statistic is the total space allocated by
Xcalls to malloc.  It is \fInot\fR the memory high-water mark.  After
Xthe input file is processed, memory is only allocated when refraction
Xoccurs (to push media onto a stack) and when raytracing height fields
X(to dynamically allocate triangles).
X.PP
XThe image produced will always be 24 bits deep.
X.PP
XExplicit or implicit specification of vectors of length
Xless than \fIepsilon\fR (1.E-6) results in undefined behavior.
X.br
X.SH "SEE ALSO"
Xrle(5)
END_OF_FILE
if test 35763 -ne `wc -c <'doc/rayshade.1'`; then
    echo shar: \"'doc/rayshade.1'\" unpacked with wrong size!
fi
# end of 'doc/rayshade.1'
fi
echo shar: End of archive 8 \(of 8\).
cp /dev/null ark8isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 ; do
    if test ! -f ark${I}isdone ; then
	MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 8 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
-- 
Please send comp.sources.unix-related mail to rsalz at uunet.uu.net.
Use a domain-based address or give alternate paths, or you may lose out.