1 files changed, 441 insertions, 0 deletions
diff --git a/solid.txi b/solid.txi
new file mode 100644
index 0000000..102214f
--- /dev/null
+++ b/solid.txi
@@ -0,0 +1,441 @@
+@ifset html
+<A NAME="Solid">
+@end ifset
+@code{(require 'solid)}
+@ifset html
+</A>
+@end ifset
+@ftindex solids
+@ftindex solid
+@ftindex solid-modeling
+
+@noindent
+@uref{http://swissnet.ai.mit.edu/~jaffer/Solid/#Example} gives an
+example use of this package.
+
+
+@defun vrml node @dots{}
+Returns the VRML97 string (including header) of the concatenation
+of strings @var{nodes}, @dots{}.
+@end defun
+
+@defun vrml-append node1 node2 @dots{}
+Returns the concatenation with interdigitated newlines of
+strings @var{node1}, @var{node2}, @dots{}.
+@end defun
+
+@defun vrml-to-file file node @dots{}
+Writes to file named @var{file} the VRML97 string (including header) of
+the concatenation of strings @var{nodes}, @dots{}.
+@end defun
+
+@defun world:info title info @dots{}
+Returns a VRML97 string setting the title of the file in which
+it appears to @var{title}.  Additional strings @var{info}, @dots{} are comments.
+@end defun
+@noindent
+
+VRML97 strings passed to @code{vrml} and @code{vrml-to-file} as
+arguments will appear in the resulting VRML code.  This string turns
+off the headlight at the viewpoint:
+@example
+" NavigationInfo @{headlight FALSE@}"
+@end example
+
+
+@defun scene:panorama front right back left top bottom
+Specifies the distant images on the inside faces of the cube
+enclosing the virtual world.
+@end defun
+
+@defun scene:sphere colors angles
+
+
+@var{colors} is a list of color objects.  Each may be of type @ref{Color
+Data-Type, color}, a 24-bit sRGB integer, or a list of 3 numbers
+between 0.0 and 1.0.
+
+@var{angles} is a list of non-increasing angles the same length as
+@var{colors}.  Each angle is between 90 and -90 degrees.  If 90 or -90 are not
+elements of @var{angles}, then the color at the zenith and nadir are taken from
+the colors paired with the angles nearest them.
+
+@code{scene:sphere} fills horizontal bands with interpolated colors on the backgroud
+sphere encasing the world.
+@end defun
+
+@defun scene:sky-and-dirt
+Returns a blue and brown backgroud sphere encasing the world.
+@end defun
+
+@defun scene:sky-and-grass
+Returns a blue and green backgroud sphere encasing the world.
+@end defun
+
+@defun scene:sun latitude julian-day hour turbidity strength
+
+
+@defunx scene:sun latitude julian-day hour turbidity
+
+@var{latitude} is the virtual place's latitude in degrees.  @var{julian-day} is an integer from
+0 to 366, the day of the year.  @var{hour} is a real number from 0 to 24 for
+the time of day; 12 is noon.  @var{turbidity} is the degree of fogginess described
+in @xref{Daylight, turbidity}.
+
+@code{scene:sun} returns a bright yellow, distant sphere where the sun would be at
+@var{hour} on @var{julian-day} at @var{latitude}.  If @var{strength} is positive, included is a light source of @var{strength}
+(default 1).
+@end defun
+
+@defun scene:overcast latitude julian-day hour turbidity strength
+
+
+@defunx scene:overcast latitude julian-day hour turbidity
+
+@var{latitude} is the virtual place's latitude in degrees.  @var{julian-day} is an integer from
+0 to 366, the day of the year.  @var{hour} is a real number from 0 to 24 for
+the time of day; 12 is noon.  @var{turbidity} is the degree of cloudiness described
+in @xref{Daylight, turbidity}.
+
+@code{scene:overcast} returns an overcast sky as it might look at @var{hour} on @var{julian-day} at @var{latitude}.  If @var{strength}
+is positive, included is an ambient light source of @var{strength} (default 1).
+@end defun
+@noindent
+Viewpoints are objects in the virtual world, and can be transformed
+individually or with solid objects.
+
+
+@defun scene:viewpoint name distance compass pitch
+
+
+@defunx scene:viewpoint name distance compass
+Returns a viewpoint named @var{name} facing the origin and placed @var{distance} from it.
+@var{compass} is a number from 0 to 360 giving the compass heading.  @var{pitch} is a
+number from -90 to 90, defaulting to 0, specifying the angle from the
+horizontal.
+@end defun
+
+@defun scene:viewpoints proximity
+Returns 6 viewpoints, one at the center of each face of a cube
+with sides 2 * @var{proximity}, centered on the origin.
+@end defun
+@subheading Light Sources
+
+@noindent
+In VRML97, lights shine only on objects within the same children node
+and descendants of that node.  Although it would have been convenient
+to let light direction be rotated by @code{solid:rotation}, this
+restricts a rotated light's visibility to objects rotated with it.
+
+@noindent
+To workaround this limitation, these directional light source
+procedures accept either Cartesian or spherical coordinates for
+direction.  A spherical coordinate is a list @code{(@var{theta}
+@var{azimuth})}; where @var{theta} is the angle in degrees from the
+zenith, and @var{azimuth} is the angle in degrees due west of south.
+
+@noindent
+It is sometimes useful for light sources to be brighter than @samp{1}.
+When @var{intensity} arguments are greater than 1, these functions
+gang multiple sources to reach the desired strength.
+
+
+@defun light:ambient color intensity
+
+
+@defunx light:ambient color
+Ambient light shines on all surfaces with which it is grouped.
+
+@var{color} is a an object of type @ref{Color Data-Type, color}, a 24-bit sRGB
+integer, or a list of 3 numbers between 0.0 and 1.0.  If @var{color} is #f,
+then the default color will be used.  @var{intensity} is a real non-negative number
+defaulting to @samp{1}.
+
+@code{light:ambient} returns a light source or sources of @var{color} with total strength of @var{intensity}
+(or 1 if omitted).
+@end defun
+
+@defun light:directional color direction intensity
+
+
+@defunx light:directional color direction
+
+@defunx light:directional color
+Directional light shines parallel rays with uniform intensity on all
+objects with which it is grouped.
+
+@var{color} is a an object of type @ref{Color Data-Type, color}, a 24-bit sRGB
+integer, or a list of 3 numbers between 0.0 and 1.0.  If @var{color} is #f,
+then the default color will be used.
+
+@var{direction} must be a list or vector of 2 or 3 numbers specifying the direction
+to this light.  If @var{direction} has 2 numbers, then these numbers are the angle
+from zenith and the azimuth in degrees; if @var{direction} has 3 numbers, then
+these are taken as a Cartesian vector specifying the direction to the
+light source.  The default direction is upwards; thus its light will
+shine down.
+
+@var{intensity} is a real non-negative number defaulting to @samp{1}.
+
+@code{light:directional} returns a light source or sources of @var{color} with total strength of @var{intensity},
+shining from @var{direction}.
+@end defun
+
+@defun light:beam attenuation radius aperture peak
+
+
+@defunx light:beam attenuation radius aperture
+
+@defunx light:beam attenuation radius
+
+@defunx light:beam attenuation
+
+@var{attenuation} is a list or vector of three nonnegative real numbers specifying
+the reduction of intensity, the reduction of intensity with distance,
+and the reduction of intensity as the square of distance.  @var{radius} is the
+distance beyond which the light does not shine.  @var{radius} defaults to
+@samp{100}.
+
+@var{aperture} is a real number between 0 and 180, the angle centered on the
+light's axis through which it sheds some light.  @var{peak} is a real number
+between 0 and 90, the angle of greatest illumination.
+@end defun
+
+@defun light:point location color intensity beam
+
+
+@defunx light:point location color intensity
+
+@defunx light:point location color
+
+@defunx light:point location
+
+Point light radiates from @var{location}, intensity decreasing with distance,
+towards all objects with which it is grouped.
+
+@var{color} is a an object of type @ref{Color Data-Type, color}, a 24-bit sRGB
+integer, or a list of 3 numbers between 0.0 and 1.0.  If @var{color} is #f,
+then the default color will be used.  @var{intensity} is a real non-negative number
+defaulting to @samp{1}.  @var{beam} is a structure returned by
+@code{light:beam} or #f.
+
+@code{light:point} returns a light source or sources at @var{location} of @var{color} with total strength
+@var{intensity} and @var{beam} properties.  Note that the pointlight itself is not visible.
+To make it so, place an object with emissive appearance at @var{location}.
+@end defun
+
+@defun light:spot location direction color intensity beam
+
+
+@defunx light:spot location direction color intensity
+
+@defunx light:spot location direction color
+
+@defunx light:spot location direction
+
+@defunx light:spot location
+
+Spot light radiates from @var{location} towards @var{direction}, intensity decreasing with
+distance, illuminating objects with which it is grouped.
+
+@var{direction} must be a list or vector of 2 or 3 numbers specifying the direction
+to this light.  If @var{direction} has 2 numbers, then these numbers are the angle
+from zenith and the azimuth in degrees; if @var{direction} has 3 numbers, then
+these are taken as a Cartesian vector specifying the direction to the
+light source.  The default direction is upwards; thus its light will
+shine down.
+
+@var{color} is a an object of type @ref{Color Data-Type, color}, a 24-bit sRGB
+integer, or a list of 3 numbers between 0.0 and 1.0.  If @var{color} is #f,
+then the default color will be used.
+
+@var{intensity} is a real non-negative number defaulting to @samp{1}.
+
+@code{light:spot} returns a light source or sources at @var{location} of @var{direction} with total strength
+@var{color}.  Note that the spotlight itself is not visible.  To make it so,
+place an object with emissive appearance at @var{location}.
+@end defun
+@subheading Object Primitives
+
+
+@defun solid:box geometry appearance
+
+
+@defunx solid:box geometry
+@var{geometry} must be a number or a list or vector of three numbers.  If @var{geometry} is a
+number, the @code{solid:box} returns a cube with sides of length @var{geometry} centered on the
+origin.  Otherwise, @code{solid:box} returns a rectangular box with dimensions @var{geometry}
+centered on the origin.  @var{appearance} determines the surface properties of the
+returned object.
+@end defun
+
+@defun solid:cylinder radius height appearance
+
+
+@defunx solid:cylinder radius height
+Returns a right cylinder with dimensions @var{radius} and @code{(abs @var{height})}
+centered on the origin.  If @var{height} is positive, then the cylinder ends
+will be capped.  @var{appearance} determines the surface properties of the returned
+object.
+@end defun
+
+@defun solid:disk radius thickness appearance
+
+
+@defunx solid:disk radius thickness
+@var{thickness} must be a positive real number.  @code{solid:disk} returns a circular disk
+with dimensions @var{radius} and @var{thickness} centered on the origin.  @var{appearance} determines the
+surface properties of the returned object.
+@end defun
+
+@defun solid:cone radius height appearance
+
+
+@defunx solid:cone radius height
+Returns an isosceles cone with dimensions @var{radius} and @var{height} centered on
+the origin.  @var{appearance} determines the surface properties of the returned
+object.
+@end defun
+
+@defun solid:pyramid side height appearance
+
+
+@defunx solid:pyramid side height
+Returns an isosceles pyramid with dimensions @var{side} and @var{height} centered on
+the origin.  @var{appearance} determines the surface properties of the returned
+object.
+@end defun
+
+@defun solid:sphere radius appearance
+
+
+@defunx solid:sphere radius
+Returns a sphere of radius @var{radius} centered on the origin.  @var{appearance} determines
+the surface properties of the returned object.
+@end defun
+
+@defun solid:ellipsoid geometry appearance
+
+
+@defunx solid:ellipsoid geometry
+@var{geometry} must be a number or a list or vector of three numbers.  If @var{geometry} is a
+number, the @code{solid:ellipsoid} returns a sphere of diameter @var{geometry} centered on the origin.
+Otherwise, @code{solid:ellipsoid} returns an ellipsoid with diameters @var{geometry} centered on the
+origin.  @var{appearance} determines the surface properties of the returned object.
+@end defun
+
+@defun solid:basrelief width height depth colorray appearance
+
+
+@defunx solid:basrelief width height depth appearance
+
+@defunx solid:basrelief width height depth
+One of @var{width}, @var{height}, or @var{depth} must be a 2-dimensional array; the others must
+be real numbers giving the length of the basrelief in those
+dimensions.  The rest of this description assumes that @var{height} is an
+array of heights.
+
+@code{solid:basrelief} returns a @var{width} by @var{depth} basrelief solid with heights per array @var{height} with
+the buttom surface centered on the origin.
+
+If present, @var{appearance} determines the surface properties of the returned
+object.  If present, @var{colorray} must be an array of objects of type
+@ref{Color Data-Type, color}, 24-bit sRGB integers or lists of 3
+numbers between 0.0 and 1.0.
+
+If @var{colorray}'s dimensions match @var{height}, then each element of @var{colorray} paints its
+corresponding vertex of @var{height}.  If @var{colorray} has all dimensions one smaller
+than @var{height}, then each element of @var{colorray} paints the corresponding face of
+@var{height}.  Other dimensions for @var{colorray} are in error.
+@end defun
+@subheading Surface Attributes
+
+
+@defun solid:color diffuseColor ambientIntensity specularColor shininess emissiveColor transparency
+
+
+@defunx solid:color diffuseColor ambientIntensity specularColor shininess emissiveColor
+
+@defunx solid:color diffuseColor ambientIntensity specularColor shininess
+
+@defunx solid:color diffuseColor ambientIntensity specularColor
+
+@defunx solid:color diffuseColor ambientIntensity
+
+@defunx solid:color diffuseColor
+
+Returns an @dfn{appearance}, the optical properties of the objects
+@cindex appearance
+with which it is associated.  @var{ambientIntensity}, @var{shininess}, and @var{transparency} must be numbers between 0
+and 1.  @var{diffuseColor}, @var{specularColor}, and @var{emissiveColor} are objects of type @ref{Color Data-Type, color},
+24-bit sRGB integers or lists of 3 numbers between 0.0 and 1.0.
+If a color argument is omitted or #f, then the default color will be used.
+@end defun
+
+@defun solid:texture image color scale rotation center translation
+
+
+@defunx solid:texture image color scale rotation center
+
+@defunx solid:texture image color scale rotation
+
+@defunx solid:texture image color scale
+
+@defunx solid:texture image color
+
+@defunx solid:texture image
+
+Returns an @dfn{appearance}, the optical properties of the objects
+@cindex appearance
+with which it is associated.  @var{image} is a string naming a JPEG or PNG
+image resource.  @var{color} is #f, a color, or the string returned by
+@code{solid:color}.  The rest of the optional arguments specify
+2-dimensional transforms applying to the @var{image}.
+
+@var{scale} must be #f, a number, or list or vector of 2 numbers specifying the
+scale to apply to @var{image}.  @var{rotation} must be #f or the number of degrees to
+rotate @var{image}.  @var{center} must be #f or a list or vector of 2 numbers specifying
+the center of @var{image} relative to the @var{image} dimensions.  @var{translation} must be #f or a
+list or vector of 2 numbers specifying the translation to apply to @var{image}.
+@end defun
+@subheading Aggregating Objects
+
+
+@defun solid:center-row-of number solid spacing
+Returns a row of @var{number} @var{solid} objects spaced evenly @var{spacing} apart.
+@end defun
+
+@defun solid:center-array-of number-a number-b solid spacing-a spacing-b
+Returns @var{number-b} rows, @var{spacing-b} apart, of @var{number-a} @var{solid} objects @var{spacing-a} apart.
+@end defun
+
+@defun solid:center-pile-of number-a number-b number-c solid spacing-a spacing-b spacing-c
+Returns @var{number-c} planes, @var{spacing-c} apart, of @var{number-b} rows, @var{spacing-b} apart, of @var{number-a} @var{solid} objects @var{spacing-a} apart.
+@end defun
+
+@defun solid:arrow center
+
+@var{center} must be a list or vector of three numbers.  Returns an upward
+pointing metallic arrow centered at @var{center}.
+
+
+@defunx solid:arrow
+Returns an upward pointing metallic arrow centered at the origin.
+@end defun
+@subheading Spatial Transformations
+
+
+@defun solid:translation center solid @dots{}
+@var{center} must be a list or vector of three numbers.  @code{solid:translation} Returns an
+aggregate of @var{solids}, @dots{} with their origin moved to @var{center}.
+@end defun
+
+@defun solid:scale scale solid @dots{}
+@var{scale} must be a number or a list or vector of three numbers.  @code{solid:scale}
+Returns an aggregate of @var{solids}, @dots{} scaled per @var{scale}.
+@end defun
+
+@defun solid:rotation axis angle solid @dots{}
+@var{axis} must be a list or vector of three numbers.  @code{solid:rotation} Returns an
+aggregate of @var{solids}, @dots{} rotated @var{angle} degrees around the axis @var{axis}.
+@end defun