#! /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 'Doc/Guide/objects.tex' <<'END_OF_FILE'
X\chapter{Object Definition}
X
XObjects in {\rayshade} are composed of relatively simple {\em primitive}
Xobjects.  These primitives may be used by themselves, or they
Xmay be combined to form more complex objects known as {\em aggregates}.
XA special family of aggregate objects,
X{\em Constructive Solid Geometry} or CSG
Xobjects, are the result of a boolean operations applied to
Xprimitive, aggregate, or CSG objects.
X
XThis chapter describes objects from a strictly geometric point of
Xview.  Later chapters on surfaces, textures, and shading describe
Xhow object appearances are defined.
X
XAn {\em instance} is an object that has optionally been transformed
Xand
Xtextured.  They are the entities that are actually rendered by
X{\rayshade}; when you specify that, for example, a textured
Xsphere is to be rendered, you are said to be instantiating
Xthe textured sphere.
XAn instance
Xis specified as a primitive, aggregate, or CSG object that
Xis followed by optional transformation and texturing information.
XTransformations and textures are described in Chapters 7 and 8 respectively.
X
X\section{The World Object}
X
XWriting a {\rayshade} input file is principally
Xa matter of defining a special aggregate object, the World object,
Xwhich is a list of the objects in the scene.  When writing a {\rayshade}
Xinput file, all objects that are instantiated outside of object-definition
Xblocks are added to the World object; you need not (nor should you)
Xdefine the World object explicitly in the input file.
X
X\section{Primitives}
X
XPrimitive objects are the building box with which other objects are
Xcreated.  Each primitive type has associated with it specialized
Xmethods for
Xcreation,
Xintersection with a ray,
Xbounding box calculation,
Xsurface normal calculation,
Xray enter/exit classification,
Xand for the computation 2D texture coordinates termed {\em u-v}
Xcoordinates.
XThis latter method is often referred to as the {\em inverse mapping}
Xmethod.
X
XWhile most of these methods should be of little concern to you, the
Xinverse mapping methods
Xwill affect the way in which certain textures are applied to primitives.
XInverse mapping is a matter of computing normalized $u$ and $v$ coordinates
Xfor a given point on the surface of the primitive.  For planar objects,
Xthe $u$ and $v$ coordinates of a point are computed
Xby linear interpolation based upon the $u$ and $v$ coordinates assigned
Xto vertices or other known points on the primitive.  For non-planar
Xobjects, $uv$ computation can be considerably more involved.
X
XThis section briefly describes each primitive and
Xthe syntax that should be used to create an instance of the primitive.
XIt also describes the inverse mapping method, if any, for each type.
X
X\begin{defprim}{blob}{{\em thresh st r} \evec{p} [{\em st r} \evec{p} \ldots]}
X	Defines a blob with consisting of a threshold equal to {\em thresh},
X	and a
X	group of one or more metaballs.  Each metaball is defined by 
X	its position \evec{p}, radius {\em r}, and strength {\em st}.
X\end{defprim}
XThe metaballs affect each other according to a superimposed
Xdensity distribution:
X\[
XF(x,y,z) = \sum_{i=0}^n b_{i}e^{-d_{i}} - T = 0
X\]
XThere is no inverse mapping method for blobs.
X
X\begin{defprim}{box}{\evec{corner1} \evec{corner2}}
X	Creates an axis-aligned box
X	which has \evec{corner1} and \evec{corner2} as
X	opposite corners.
X\end{defprim}
XTransformations may be applied to the box if a non-axis-aligned instance
Xis required.  There is no inverse mapping method for boxes.
X
X\begin{defprim}{sphere}{{\em radius} \evec{center}}
X	Creates a sphere with the given {\em radius} and centered at the
X	given position.
X\end{defprim}
XNote that ellipsoids may be created by applying the proper scaling
Xto a sphere.  Inverse mapping on the sphere is accomplished
Xby computing the longitude and latitude of the point on the sphere,
Xwith the $u$ value corresponding to longitude and $v$ to latitude.
XOn an untransformed sphere, the $z$ axis defines the poles, and the
X$x$ axis intersects the sphere at $u = 0$, $v = 0.5$.  There are
Xdegeneracies at the poles: the south pole contains all points of
Xlatitude 0., the north all points of latitude 1.
X
X\begin{defprim}{torus}{{\em rmajor rminor} \evec{center} \evec{up}}
X	Creates a torus centered at \evec{center} by rotating
X	a circle with the given minor radius around the center
X	point at a distance equal to the major radius. 
X\end{defprim}
XIn tori inverse mapping,
Xthe $u$ value is computed using the angle of rotation about the
Xup vector, and the $v$ value is computing the angle of rotation
Xaround the tube, with $v=0$ occuring on the innermost point of the tube.
X
X\begin{defprim}{triangle}{\evec{p1} \evec{p2} \evec{p3}}
X	Creates a triangle with the given vertices.
X\end{defprim}
X
X\begin{defprim}{triangle}{\evec{p1} \evec{n1} \evec{p2} \evec{n2}
X	\evec{p3} \evec{n3}}
X	Creates a Phong-shaded triangle with the given vertices and
X	vertex normals.
X\end{defprim}
XFor both Phong- and flat-shaded triangles, the $u$ axis is the
Xvector from \evec{p1} to \evec{p2}, and the $v$ axis the vector
Xfrom \evec{p1} to \evec{p3}.  There is a degeneracy at
X\evec{p3}, which contains all points with $v = 1.0$.  This default
Xmapping may be modified using the {\tt triangleuv} primitive described
Xbelow.
X
X\begin{defprim}{triangleuv}{\evec{p1} \evec{n1} \evec{uv1}
X  \evec{p2} \evec{n2} \evec{uv2}
X  \evec{p3} \evec{n3} \evec{uv3}}
X	Creates a Phong-shaded triangle with the given vertices,
X	vertex normals.  When performing texturing, the
X	{\em uv} given for each vertex are used instead of the
X	default values.
X\end{defprim}
XWhen computing $uv$ coordinates within the interior of the
Xtriangle, linear interpolation of the coordinates associated with
Xeach triangle vertex is used.
X
X\begin{defprim}{poly}{\evec{p1} \evec{p2} \evec{p3} [\evec{p4} \ldots ]}
X	Creates a polygon with the given vertices. The vertices
X	should be given in counter-clockwise order as one is
X	looking at the ``front'' side of the polygon.  The number of
X	vertices in a polygon is limited only by available memory.
X\end{defprim}
XInverse mapping for arbitrary polygons is problematical.
X{\Rayshade}
Xpunts and equates $u$ with the $x$ coordinate of the point of intersection,
Xand $v$ with the $y$ coordinate.
X
X\begin{defprim}{heightfield}{{\em file}}
X	Creates a height field defined by the altitude data stored
X	in the named {\em file}.  The height field is based upon
X	perturbations of the unit square in the $z=0$ plane, and is
X	rendered as a surface tessellated by right isosceles triangles.
X\end{defprim}
XSee Appendix C for a discussion of the format of a height field file.
XHeight field inverse mapping is straight-forward:  $u$ is the
X$x$ coordinate of the point of intersection, $v$ the $y$ coordinate.
X
X\begin{defprim}{plane}{\evec{point} \evec{normal}}
X	Creates a plane that passes through the given point and
X	has the specified normal.
X\end{defprim}
XInverse mapping on the plane is identical to polygonal inverse mapping.
X
X\begin{defprim}{cylinder}{{\em radius} \evec{bottom} \evec{top}}
X	Creates a cylinder that extends from \evec{bottom} to \evec{top}
X	and has the indicated {\em radius}.  Cylinders are rendered
X	{\em without} endcaps.
X\end{defprim}
XThe cylinder's axis defines the $v$ axis.  The $u$ axis wraps around the
Xcylinder, with $u=0$ dependent upon the orientation of the cylinder.
X
X
X\begin{defprim}{cone}{$rad_{bottom}$ \evec{bottom} $rad_{top}$ \evec{top}}
X	Creats a (truncated) cone that extends from \evec{bottom} to
X	\evec{top}.  The cone will have a radius of $rad_{bottom}$ at
X	\evec{bottom} and a radius of $rad_{top}$ at \evec{top}.
X	Cones are rendered {\em without} endcaps.
X\end{defprim}
XCone inverse mapping is analogous to cylinder mapping.
X
X\begin{defprim}{disc}{{\em radius} \evec{pos} \evec{normal}}
X	Creates a disc centered at the given position and with the
X	indicated surface normal.
X\end{defprim}
XDiscs are useful for placing
Xendcaps on cylinders and cones.
XInverse mapping for the disc is based on the computation of the
Xnormalized polar coordinates of the point of intersection.  The
Xnormalized radius
Xof the point of intersection is assigned to $u$, while the normalized angle
Xfrom a reference vector is assigned to $v$.
X
X\section{Aggregate Objects}
X
XAn aggregate is a collection of primitives, aggregate, and CSG
Xobjects.  An aggregate, once defined, may be instantiated at will,
Xwhich means that
Xcopies that are optionally transformed and textured may be made.
XIf a scene calls for the presence of many geometrically identical
Xobjects, only one such object need be defined; the one defined object
Xmay then be instantiated many times.
X
XAn aggregate is one of several possible types.  These aggregate types
Xare differentiated by the type of ray/aggregate intersection algorithm
X(often termed an {\em acceleration technique} or {\em efficiency scheme})
Xthat is used.
X
XAggregates are defined by giving a keyword that defines the
Xtype of the aggregate, followed by
Xa series of object instantiations and
Xsurface definitions, and terminated using the {\tt end} keyword.
XIf a defined object contains no instantiations, a warning message
Xis printed.
X
XThe most basic type of aggregate, the {\em list}, performs
Xintersection testing in the simplest possible way:  Each object in the
Xlist is tested for intersection with the ray in turn, and the closest
Xintersection is returned.
X
X\begin{defkey}{list}{\ldots {\tt end}}
X	Create a List object containing those objects instantiated between
X	the {\tt list}/{\tt end} pair.
X\end{defkey}
X
XThe {\em grid} aggregate
Xdivides the region of space it occupies into a number of discrete
Xbox-shaped
Xvoxels.  Each of these voxels contains a list of the objects that
Xintersect the voxel.  This discretization makes it possible to
Xrestrict the objects
Xtested for intersection to those that are likely to hit the ray,
Xand to test
Xthe objects in nearly ``closest-first'' order.
X
X\begin{defkey}{grid}{{\em xvox yvox zvox} \ldots {\tt end}}
X	Create a Grid objects composed of {\em xvox} by {\em yvox} by
X	{\em zvox} voxels containing those objects
X	instantiated between the {\tt grid}/{\tt end} pair.
X\end{defkey}
XIt is usually only worthwhile to ``engrid'' rather large,
Xcomplex collections of objects.  Grids also use a great deal more
Xmemory than List objects.
X
X\section {Constructive Solid Geometry}
X
XConstructive Solid Geometry is
Xthe process of building solid objects from other solids.
XThe three CSG
Xoperators are Union, Intersection, and Difference.  Each operator
Xacts upon two objects and produces a single object result.
XBy combining multiple levels of CSG operators, complex
Xobjects can be produced from simple primitives.
X
XThe union of two objects results in an
Xobject that encloses the space occupied by the two given objects.
XIntersection results in an object that encloses the space where the two
Xgiven objects overlap.  Difference is an order dependent operator; it
Xresults in the
Xfirst given object minus the space where the second intersected
Xthe first.
X
X\subsection{CSG in {\Rayshade}}
X
XCSG in {\rayshade} will generally operate properly when applied to
Xconjunction with
Xon boxes, spheres,
Xtori, and blobs.
XThese primitives are by nature consistent, as they all
Xenclose a portion of space (no hole from the ``inside'' to the
X``outside''), have surface normals which point outward (they
Xare not ``inside-out''), and do not have any extraneous surfaces.
X
XCSG objects may also be constructed from aggregate objects.
XThese aggregates contain
Xwhatever is listed inside, and may therefore be inconsistent.
XFor example, an object which contains a single triangle will not
Xproduce correct results in CSG models, because the triangle does not enclose
Xspace.  However, a collection of four triangles which form a pyramid
Xdoes enclose space, and if the triangle normals
Xare oriented correctly,
Xthe CSG operators should work correctly on the pyramid.
X
XCSG objects are specified by surrounding the objects upon
Xwhich to operate, as well as any associated surface-binding commands,
Xby the operator verb on one side and the {\tt end}
Xkeyword on the other:
X
X\begin{defkey}{union}{$<${\em Object}$>$ $<${\em Object}$>$
X[$<${\em Object}$>$ \ldots] {\tt end}}
X	Specify a new object defined as the union of the
X	given objects.
X\end{defkey}
X
X\begin{defkey}{difference}{$<${\em Object}$>$ $<${\em Object}$>$ 
X[$<${\em Object}$>$ \ldots] {\tt end}}
X	Specify a new object defined as the difference of the
X	given objects.
X\end{defkey}
X
X\begin{defkey}{intersect}{$<${\em Object}$>$ $<${\em Object}$>$
X[$<${\em Object}$>$ \ldots] {\tt end}}
X	Specify a new object defined as the intersection of the
X	given objects.
X\end{defkey}
X
XNote that the current implementation does not support more that two
Xobjects in a CSG list (but it is planned for a future version).
X
X% The following aren simple CSG objects using the four consistent
X% primitives:
X% 
X% union box ... difference ...
X
X\subsection{Potential CSG Problems}
X
XA consistent CSG model is one which is made
Xup of solid objects with no dangling surfaces.  In {\rayshade},
Xit is quite easy to construct inconsistent models, which will usually
Xappear incorrect in the final images.
XIn {\rayshade}, CSG is implemented by maintaining
Xthe tree structure of the CSG operations.  This tree is traversed,
Xand the operators therein applied, on a per-ray basis.
XIt is therefore difficult to verify the consistency of
Xthe model ``on the fly.''
X
XOne class of CSG problems occur when
Xsurfaces of objects being operated upon
Xcoincide.  For example, when subtracting a box from another box to make a
Xsquare cup, the result will be wrong if the tops of the two boxes
Xcoincide.  To correct this, the inner box should be made
Xslightly taller than the outer box.
XA related problem that must be
Xavoided occurs when two coincident surfaces are assigned
Xdifferent surface properties.
X
XIt may seem that the union operator is unnecessary, since
Xlisting two objects together in an aggregate results
Xin an image that appears to be the same.
XWhile the result of such a short-cut
Xmay appear the same on the exterior, the interior
Xof the resulting object will contain
Xextraneous surfaces.
XThe following examples show this quite clearly.
X
X\begin{verbatim}
X    difference
X      box -2 0 -3  2 3 3
X      union  /* change to list; note bad internal surfaces */
X        sphere 2 1 0 0
X        sphere 2 -1 0 0
X      end
X    end rotate 1 0 0 -40  rotate 0 0 1 50
X\end{verbatim}
X
XThe visual evidence of an inconsistent CSG object varies depending
Xupon the operator being used.
XWhen subtracting a consistent object from and
Xinconsistent one, the resulting object will appear to be
Xthe union of the two objects, but the shading will be incorrect.
XIt will appear to be inside-out in places, while correct
Xin other places.  The inside-out sections indicate the areas
Xwhere the problems occur.
XSuch problems are often caused by
Xpolygons with incorrectly specified
Xnormals, or by surfaces that exactly coincide (which
Xappear as partial ``Swiss cheese'' objects).
X
XThe following example illustrates an attempt to subtract a sphere from
Xa pyramid defined using an incorrectly facing triangle.  Note
Xthat the resulting image obviously points to which triangle is
Xreversed.
X
X\begin{verbatim}
X    name pyramid list
X        triangle 1 0 0  0 1 0  0 0 1
X        triangle 1 0 0  0 0 0  0 1 0
X        triangle 0 1 0  0 0 0  0 0 1
X        triangle 0 0 1  1 0 0  0 0 0  /* wrong order */
X    end
X
X    difference
X        object pyramid scale 3 3 3 rotate 0 0 1 45
X            rotate 1 0 0 -30 translate 0 -3.5 0
X        sphere 2.4 0 0 0
X    end
X\end{verbatim}
X
XBy default, cylinders and cones do not have end caps, and thus
Xare not consistent primitives.  One must usually
Xadd endcaps by listing the
Xcylinder or cone with (correctly-oriented) endcap discs in an aggregate.
X
X\section {Named Objects}
X
XA name may be associated with any primitive, aggregate, or CSG
Xobject through the use of the {\tt name}
Xkeyword:
X
X\begin{defkey}{name}{{\em objname} $<${\em Instance\/}$>$}
X	Associate {\em objname} with the given object.  The
X	specified object is not actually instantiated; it
X	is only stored under the given name.
X\end{defkey}
X
XAn object thus named may then be instantiated (with possible
Xadditional transforming and texturing) via the {\tt object} keyword:
X
X\begin{defkey}{object}{{\em objname} [$<$Transformations$>$] [$<$Textures$>$]}
X	Instantiate a copy of the object associated with {\em objname}.
X	If given, the transformations and textures are composed
X	with any already associated with
X	the object being instantiated.
X\end{defkey}
END_OF_FILE
if test 16473 -ne `wc -c <'Doc/Guide/objects.tex'`; then
    echo shar: \"'Doc/Guide/objects.tex'\" unpacked with wrong size!
fi
# end of 'Doc/Guide/objects.tex'
fi
if test -f 'etc/rsconvert/yacc.y' -a "${1}" != "-c" ; then 
  echo shar: Will not clobber existing file \"'etc/rsconvert/yacc.y'\"
else
echo shar: Extracting \"'etc/rsconvert/yacc.y'\" \(14099 characters\)
sed "s/^X//" >'etc/rsconvert/yacc.y' <<'END_OF_FILE'
X/* yacc.y								   */
X/*									   */
X/* Copyright (C) 1989, 1991, Craig E. Kolb				   */
X/* All rights reserved.							   */
X/*									   */
X/* This software may be freely copied, modified, and redistributed,	   */
X/* provided that this copyright notice is preserved on all copies.	   */
X/*									   */
X/* You may not distribute this software, in whole or in part, as part of   */
X/* any commercial product without the express consent of the authors.      */
X/* 									   */
X/* There is no warranty or other guarantee of fitness of this software	   */
X/* for any purpose.  It is provided solely "as is".			   */
X/* $Id: yacc.y,v 4.0.1.3 92/02/07 11:05:21 cek Exp Locker: cek $ */
X%{
X#include 
X#include "libcommon/common.h"
X
X#define NEWLINE()	WriteNewline()
X/*#define NEWLINE()	printf("\n")*/
X#define LIST	0
X#define GRID	1
Xchar yyfilename[BUFSIZ];
Xextern int yylineno;
X%}
X%union {
X	char *c;
X	int i;
X	double d;
X	Color col;
X	Vector v;
X};
X%token  tFLOAT
X%token  tSTRING tHASHTHING
X%token  tINT
X%type  Fnumber sFnumber
X%type