From 5145dd3aa0c02c9fc496d1432fc4410674206e1d Mon Sep 17 00:00:00 2001
From: Bryan Newbold <bnewbold@robocracy.org>
Date: Mon, 20 Feb 2017 00:05:31 -0800
Subject: Import Upstream version 3a2

---
 solid.txi | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 117 insertions(+), 6 deletions(-)

(limited to 'solid.txi')

diff --git a/solid.txi b/solid.txi
index 102214f..3058e75 100644
--- a/solid.txi
+++ b/solid.txi
@@ -10,7 +10,7 @@
 @ftindex solid-modeling
 
 @noindent
-@uref{http://swissnet.ai.mit.edu/~jaffer/Solid/#Example} gives an
+@uref{http://swiss.csail.mit.edu/~jaffer/Solid/#Example} gives an
 example use of this package.
 
 
@@ -19,20 +19,24 @@ 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
@@ -48,6 +52,7 @@ Specifies the distant images on the inside faces of the cube
 enclosing the virtual world.
 @end defun
 
+
 @defun scene:sphere colors angles
 
 
@@ -60,18 +65,21 @@ between 0.0 and 1.0.
 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
+@code{scene:sphere} fills horizontal bands with interpolated colors on the background
 sphere encasing the world.
 @end defun
 
+
 @defun scene:sky-and-dirt
-Returns a blue and brown backgroud sphere encasing the world.
+Returns a blue and brown background sphere encasing the world.
 @end defun
 
+
 @defun scene:sky-and-grass
-Returns a blue and green backgroud sphere encasing the world.
+Returns a blue and green background sphere encasing the world.
 @end defun
 
+
 @defun scene:sun latitude julian-day hour turbidity strength
 
 
@@ -87,6 +95,7 @@ in @xref{Daylight, turbidity}.
 (default 1).
 @end defun
 
+
 @defun scene:overcast latitude julian-day hour turbidity strength
 
 
@@ -100,6 +109,7 @@ 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.
@@ -115,10 +125,12 @@ 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
@@ -155,6 +167,7 @@ defaulting to @samp{1}.
 (or 1 if omitted).
 @end defun
 
+
 @defun light:directional color direction intensity
 
 
@@ -181,6 +194,7 @@ shine down.
 shining from @var{direction}.
 @end defun
 
+
 @defun light:beam attenuation radius aperture peak
 
 
@@ -201,6 +215,7 @@ 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
 
 
@@ -224,6 +239,7 @@ defaulting to @samp{1}.  @var{beam} is a structure returned by
 To make it so, place an object with emissive appearance at @var{location}.
 @end defun
 
+
 @defun light:spot location direction color intensity beam
 
 
@@ -255,6 +271,7 @@ then the default color will be used.
 @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
 
 
@@ -269,16 +286,19 @@ centered on the origin.  @var{appearance} determines the surface properties of t
 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})}
+Returns a right cylinder with dimensions @code{(abs @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
+will be capped.  If @var{radius} is negative, then only the ends will appear.
+@var{appearance} determines the surface properties of the returned
 object.
 @end defun
 
+
 @defun solid:disk radius thickness appearance
 
 
@@ -288,6 +308,7 @@ with dimensions @var{radius} and @var{thickness} centered on the origin.  @var{a
 surface properties of the returned object.
 @end defun
 
+
 @defun solid:cone radius height appearance
 
 
@@ -297,6 +318,7 @@ the origin.  @var{appearance} determines the surface properties of the returned
 object.
 @end defun
 
+
 @defun solid:pyramid side height appearance
 
 
@@ -306,6 +328,7 @@ the origin.  @var{appearance} determines the surface properties of the returned
 object.
 @end defun
 
+
 @defun solid:sphere radius appearance
 
 
@@ -314,6 +337,7 @@ Returns a sphere of radius @var{radius} centered on the origin.  @var{appearance
 the surface properties of the returned object.
 @end defun
 
+
 @defun solid:ellipsoid geometry appearance
 
 
@@ -324,6 +348,26 @@ Otherwise, @code{solid:ellipsoid} returns an ellipsoid with diameters @var{geome
 origin.  @var{appearance} determines the surface properties of the returned object.
 @end defun
 
+
+@defun solid:polyline coordinates appearance
+
+
+@defunx solid:polyline coordinates
+@var{coordinates} must be a list or vector of coordinate lists or vectors
+specifying the x, y, and z coordinates of points.  @code{solid:polyline} returns lines
+connecting successive pairs of points.  If called with one argument,
+then the polyline will be white.  If @var{appearance} is given, then the polyline
+will have its emissive color only; being black if @var{appearance} does not have
+an emissive color.
+
+The following code will return a red line between points at
+@code{(1 2 3)} and @code{(4 5 6)}:
+@example
+(solid:polyline '((1 2 3) (4 5 6)) (solid:color #f 0 #f 0 '(1 0 0)))
+@end example
+@end defun
+
+
 @defun solid:basrelief width height depth colorray appearance
 
 
@@ -348,6 +392,27 @@ corresponding vertex of @var{height}.  If @var{colorray} has all dimensions one
 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
+
+
+@defun solid:text fontstyle str len appearance
+
+
+@defunx solid:text fontstyle str len
+
+@var{fontstyle} must be a value returned by @code{solid:font}.
+
+@var{str} must be a string or list of strings.
+
+@var{len} must be #f, a nonnegative integer, or list of nonnegative
+integers.
+
+@var{appearance}, if given, determines the surface properties of the returned
+object.
+
+@code{solid:text} returns a two-sided, flat text object positioned in the Z=0 plane
+of the local coordinate system
+@end defun
+
 @subheading Surface Attributes
 
 
@@ -372,6 +437,7 @@ and 1.  @var{diffuseColor}, @var{specularColor}, and @var{emissiveColor} are obj
 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
 
 
@@ -398,6 +464,44 @@ rotate @var{image}.  @var{center} must be #f or a list or vector of 2 numbers sp
 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
+
+
+@defun solid:font family style justify size spacing language direction
+
+Returns a fontstyle object suitable for passing as an argument to
+@code{solid:text}.  Any of the arguments may be #f, in which case
+its default value, which is first in each list of allowed values, is
+used.
+
+@var{family} is a case-sensitive string naming a font; @samp{SERIF},
+@samp{SANS}, and @samp{TYPEWRITER} are supported at the minimum.
+
+@var{style} is a case-sensitive string @samp{PLAIN}, @samp{BOLD},
+@samp{ITALIC}, or @samp{BOLDITALIC}.
+
+@var{justify} is a case-sensitive string @samp{FIRST}, @samp{BEGIN},
+@samp{MIDDLE}, or @samp{END}; or a list of one or two case-sensitive
+strings (same choices).  The mechanics of @var{justify} get complicated; it is
+explained by tables 6.2 to 6.7 of
+@url{http://www.web3d.org/x3d/specifications/vrml/ISO-IEC-14772-IS-VRML97WithAmendment1/part1/nodesRef.html#Table6.2}
+
+
+@var{size} is the extent, in the non-advancing direction, of the text.
+@var{size} defaults to 1.
+
+@var{spacing} is the ratio of the line (or column) offset to @var{size}.
+@var{spacing} defaults to 1.
+
+@var{language} is the RFC-1766 language name.
+
+@var{direction} is a list of two numbers: @w{@code{(@var{x} @var{y})}}.  If
+@w{@code{(> (abs @var{x}) (abs @var{y}))}}, then the text will be
+arrayed horizontally; otherwise vertically.  The direction in which
+characters are arrayed is determined by the sign of the major axis:
+positive @var{x} being left-to-right; positive @var{y} being
+top-to-bottom.
+@end defun
+
 @subheading Aggregating Objects
 
 
@@ -405,14 +509,17 @@ list or vector of 2 numbers specifying the translation to apply to @var{image}.
 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
@@ -422,6 +529,7 @@ 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
 
 
@@ -430,12 +538,15 @@ Returns an upward pointing metallic arrow centered at the origin.
 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
+
-- 
cgit v1.2.3