--- ray/src/cv/mgflib/mgfdoc.tr	1995/06/29 14:40:18	1.4
+++ ray/src/cv/mgflib/mgfdoc.tr	1997/10/16 11:42:25	1.19
@@ -5,8 +5,9 @@
 .vs 12
 .nr PD .5v
 .ds LF MGF
-.ds RF Version 1.0
-.DA May 1995
+.ds RF Version 1.1
+.\" !Remember to update date on each modification!
+.DA February 1996
 .TL
 The Materials and Geometry Format
 .AU
@@ -42,7 +43,7 @@ and sample scenes and objects at the web site,
 "http://radsite.lbl.gov/mgf/HOME.html".
 .RE
 .LP
-The standard parser provides both immediate and a long-term
+The standard parser provides both immediate and long-term
 benefits, since it presents a programming interface that is more
 stable even than the language itself.
 Unlike AutoCAD DXF and other de facto standards, a change to the
@@ -232,6 +233,7 @@ p	x y z	set point position for current vertex
 n	dx dy dz	set surface normal for current vertex
 _	_	_
 f	v1 v2 v3 ...	polygon using current material, spec. vertices
+fh	v1 v2 v3 - ...	face with explicit holes
 sph	vc radius	sphere
 cyl	v1 radius v2	truncated right cylinder (open-ended)
 cone	v1 rad1 v2 rad2	truncated right cone (open-ended)
@@ -277,14 +279,14 @@ Context	Cntl. Entity	Default Value	Field Entities	Affe
 =	=	=	=	=
 Object	o	-	-	-
 Transform	xf	-	-	T{
-f, sph, cyl, cone,
+f, fh, sph, cyl, cone,
 ring, torus, prism
 T}
 Material	m	2-sided black	T{
 sides, rd, td,
-ed, rs, ts
+ed, rs, ts, ir
 T}	T{
-f, sph, cyl, cone,
+f, fh, sph, cyl, cone,
 ring, torus, prism
 T}
 Color	c	neutral grey	T{
@@ -296,7 +298,7 @@ Vertex	v	T{
 (0,0,0),
 no normal
 T}	p, n	T{
-f, sph, cyl, cone,
+f, fh, sph, cyl, cone,
 ring, torus, prism
 T}
 .TE
@@ -815,6 +817,7 @@ Geometry
 .TS
 lw(.75i) lw(1.75i) lw(3i).
 f	v1 v2 v3 ...	polygon using current material, spec. vertices
+fh	v1 v2 v3 - ...	face with explicit holes
 sph	vc radius	sphere
 cyl	v1 radius v2	truncated right cylinder (open-ended)
 cone	v1 rad1 v2 rad2	truncated right cone (open-ended)
@@ -1266,7 +1269,8 @@ corresponds to the measurement at
 Values in between are separated by
 .I "(l_max-l_min)/(N-1)"
 nanometers.
-All values must be non-negative, and the spectrum outside of the
+All values should be non-negative unless defining a component for
+complementary color mixing, and the spectrum outside of the
 specified range is assumed to be zero.
 (The visible range is 380 to 780 nm.)\0
 The actual units and scale of the measurements do not matter,
@@ -1673,7 +1677,7 @@ EXAMPLE
 # A 100-watt incandescent bulb (1600 lumens) modeled as a sphere
 m
 	c
-	cct 3000
+		cct 3000
 	ed 87712
 v cent =
 	p 0 0 0
@@ -1899,6 +1903,8 @@ and
 require a normal direction.
 An
 .UL f
+or
+.UL fh
 entity will interpolate vertex normals if given, and
 use the polygon plane normal otherwise.
 See the
@@ -1938,6 +1944,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL n,
 .UL p,
 .UL prism,
@@ -1982,6 +1989,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL n,
 .UL prism,
 .UL ring,
@@ -2028,6 +2036,7 @@ xf
 SEE ALSO
 .LP
 .UL f,
+.UL fh,
 .UL p,
 .UL prism,
 .UL ring,
@@ -2067,15 +2076,22 @@ when normals are used.
 Also, specified normals should point in the general direction of the
 surface for best results.
 .LP
-There is no explicit representation of holes in MGF.  A hole must be
-represented implicitly by connecting vertices to form "seams."  For
+There is no explicit representation of holes in this entity, but see
+the
+.UL fh
+entity for an alternative specification.
+.LP
+A hole may be represented implicitly in a face entity
+by connecting vertices to form "seams."
+For
 example, a wall with a window in it might look as shown in Figure 1.
 In many systems, the wall itself would be represented with the first
 list of vertices, (v1,v2,v3,v4) and the hole associated with that
-wall as a second set of vertices (v5,v6,v7,v8).  In MGF, we must
+wall as a second set of vertices (v5,v6,v7,v8).
+Using the face entity, we must
 give the whole thing as a single polygon, connecting the vertices so
 as to create a "seam," as shown in Figure 2.
-This could be written in MGF as "f v1 v2 v3 v4 v5 v6 v7 v8 v5 v4".
+This could be written as "f v1 v2 v3 v4 v5 v6 v7 v8 v5 v4".
 .LP
 It is very important that the order of the hole be opposite to the
 order of the outer perimeter, otherwise the polygon will be
@@ -2124,12 +2140,68 @@ SEE ALSO
 .LP
 .UL cone,
 .UL cyl,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
 .UL sph,
 .UL torus,
 .UL v
+.ds RH FH
+.bp
+.SH
+NAME
+.LP
+fh - create a polygonal face with explicit holes
+.SH
+SYNOPSIS
+.LP
+.B fh
+.I "p1 p2 ... - h1.1 h1.2 ... - h2.1 h2.2 ..."
+.SH
+DESCRIPTION
+.LP
+Create a polygonal face with optional holes made of the current material.
+The first contour is the outer perimeter, with vertices given in
+counter-clockwise order as seen from the front side (the same as the
+.UL f
+entity).
+A hole is indicated by a hyphen ('-') followed by the hole's
+vertices, given in clockwise order as seen from the front side.
+Multiple hole contours are separated by additional hyphens.
+There must be at least three vertices for each contour, and the
+last vertex is implicitly connected to the first.
+If any vertex is undefined, an error will result.
+.LP
+If any vertices have associated surface normals, they will be used
+instead of the average plane normal, though it is safest to specify
+either all normals or no normals, and to stick with triangles
+when normals are used.
+Also, specified normals should point in the general direction of the
+surface for best results.
+.LP
+Vertices should not be shared between any two contours.
+I.e., a hole should not share a vertex or edge with the perimeter or
+another hole, or incorrect rendering may result.
+.SH
+EXAMPLE
+.DS
+# Make a wall with a window using an explicit hole.
+# (See Figures 1 and 2.)
+fh v1 v2 v3 v4 - v5 v6 v7 v8
+.DE
+.SH
+SEE ALSO
+.LP
+.UL cone,
+.UL cyl,
+.UL f,
+.UL m,
+.UL prism,
+.UL ring,
+.UL sph,
+.UL torus,
+.UL v
 .ds RH SPH
 .bp
 .SH
@@ -2178,6 +2250,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2225,7 +2298,7 @@ o stylus
 		p 0 0 .005
 	v vend =
 		p 0 0 .05
-	cyl vtip1 .0015
+	cyl vtip1 .0015 vend
 	sph vend .0015
 	cone vtip0 0 vtip1 .0015
 o
@@ -2235,6 +2308,7 @@ SEE ALSO
 .LP
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2307,6 +2381,7 @@ SEE ALSO
 .LP
 .UL cyl,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2373,6 +2448,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL ring,
 .UL sph,
@@ -2387,7 +2463,7 @@ ring - create a circular ring with inner and outer rad
 .SH
 SYNOPSIS
 .LP
-.B cyl
+.B ring
 .I "vc rmin rmax"
 .SH
 DESCRIPTION
@@ -2429,6 +2505,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL sph,
@@ -2489,6 +2566,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2500,9 +2578,12 @@ SEE ALSO
 .NH
 MGF Translators
 .LP
-Initially, there are four translators for MGF data, but only
-one of these is distributed with the MGF parser itself,
-.I mgfilt.
+Initially, there are six translators for MGF data, and
+three of these are distributed with the MGF parser itself,
+.I mgfilt,
+.I mgf2inv
+and
+.I 3ds2mgf.
 Two of the other translators,
 .I mgf2rad
 and
@@ -2515,7 +2596,7 @@ package\(dg.
 nestor.epfl.ch, or by WWW from
 "http://radsite.lbl.gov/radiance/HOME.html"
 .FE
-A third translator,
+The sixth translator,
 .I mgf2meta,
 converts to a 2-dimensional line plot, and is also
 distributed with Radiance.
@@ -2532,6 +2613,14 @@ unwanted entities.
 In future releases of MGF, this utility will also be handy for
 taking new entities and producing older versions of MGF for
 translators that have not yet been updated properly.
+.LP
+Mgf2inv converts from MGF to Inventor or VRML format.
+Some information is lost, because these formats do not support
+physical light sources or materials.
+.LP
+3ds2mgf converts from 3D Studio binary format to MGF.
+Care must be taken to correct for errors in the material descriptions,
+since 3D Studio is completely non-physical.
 .ds LH Translators
 .ds RH MGFILT
 .bp
@@ -2566,6 +2655,10 @@ In the first form, a single integer is given for the
 of MGF that is to be produced.
 Since MGF is in its first major release, this is not yet a useful
 form, but it will be when the second major release comes out.
+This has the necessary side-effect of expanding all included files.
+(See the
+.UL i
+entity.)\0
 .LP
 In the second form,
 .I mgfilt
@@ -2590,7 +2683,159 @@ mgfilt f,v,p,xf input.mgf > flatpoly.mgf
 .SH
 SEE ALSO
 .LP
-mgf2rad, rad2mgf
+i, mgf2inv, mgf2rad, rad2mgf
+.ds RH MGF2INV
+.bp
+.SH
+NAME
+.LP
+mgf2inv - convert from MGF to Inventor or VRML format
+.SH
+SYNOPSIS
+.LP
+.B mgf2inv
+[
+.B "-1|-2|-vrml"
+]
+[
+.B input ..
+]
+.SH
+DESCRIPTION
+.LP
+.I Mgf2inv
+takes one or more MGF input files and converts it to
+Inventor or VRML format.
+If the
+.I \-1
+option is used, then Inventor 1.0 ASCII output is produced.
+If the
+.I \-2
+option is used, then Inventor 2.0 ASCII output is produced.
+(This is the default.)\0
+If the
+.I \-vrml
+option is used, then VRML 1.0 ASCII output is produced.
+.LP
+This converter does not work properly for light sources, since
+the output formats do not support IES-type luminaires with recorded
+distributions.
+Also, some material information may be lost because Inventor lacks
+a physically valid reflectance model.
+.SH
+EXAMPLES
+.LP
+To take an MGF file and convert it to VRML format:
+.IP
+mgf2inv -vrml myscene.mgf > myscene.iv
+.SH
+SEE ALSO
+.LP
+mgf2rad(1), mgfilt(1), 3ds2mgf(1), rad2mgf(1)
+.ds RH 3DS2MGF
+.bp
+.SH
+NAME
+.LP
+3ds2mgf - convert 3D Studio binary file to Materials and Geometry Format
+.SH
+SYNOPSIS
+.LP
+.B 3ds2mgf
+.B input
+[
+.B output
+]
+[
+.B -lMatlib
+][
+.B -xObjname
+][
+.B -sAngle
+][
+.B -aAnimfile
+][
+.B -fN
+]
+.SH
+DESCRIPTION
+.LP
+.I 3ds2mgf
+converts a 3D Studio binary scene description
+to the Materials and Geometry Format (MGF).
+If no output file name is given, the input root name
+will be taken as the output root, and an "mgf" extension
+will be added.
+This file will contain any light sources and materials, and an include
+statement for a similarly named file ending in "inc", which will contain
+the MGF geometry of all the translated 3DS meshes.
+.LP
+The MGF material names and properties
+for the surfaces will be those assigned in 3D Studio,
+unless they are named in one or more MGF material libraries given in a
+.I -l
+option.
+.LP
+The
+.I -x
+option may be used to exclude a named object from the output.
+.LP
+The
+.I -s
+option may be used to adjust automatic mesh smoothing such that adjacent
+triangle faces with less than the given angle between them (in degrees)
+will be smoothed.
+A value of zero turns smoothing off.
+The default value is 60 degrees.
+.LP
+The
+.I -a
+option may be used to specify a 3D Studio animation file, and together with the
+.I -f
+option,
+.I 3ds2mgf
+will generate a scene description for the specified frame.
+.LP
+Note that there are no spaces between the options and their arguments.
+.SH
+LIMITATIONS
+.LP
+Obviously, since 3D Studio has no notion of physical materials, the
+translation to MGF material descriptions is very ad hoc, and it will
+usually be necessary to edit the materials and light sources in
+the output file or replace materials with proper entries from a material
+library using the
+.I -l
+option.
+.LP
+With smoothing turned on (i.e., a non-zero value for the
+.I -s
+option), vertices in the MGF output will not be linked in a proper
+mesh for each object.
+This is due to the way the automatic smoothing code was originally
+written, and is too difficult to repair.
+If a good mesh is needed, then smoothing must be turned off.
+.SH
+EXAMPLES
+.LP
+To convert a 3D Studio robot model to MGF without smoothing.
+(Output will be put into "robot.mgf" and "robot.inc".)
+.IP
+3ds2mgf robot.3ds -s0
+.LP
+To convert a DC10 jet model to MGF using a hand-created material library:
+.IP
+3ds2mgf dc10.3ds -ldc10mat.mgf
+.SH
+AUTHORS
+.LP
+Steve Anger, Jeff Bowermaster and Greg Ward
+.br
+Extended from 3ds2pov 1.8.
+.SH
+SEE ALSO
+.LP
+mgf2inv(1), mgf2meta(1), mgf2rad(1)
 .ds RH MGF2RAD
 .bp
 .SH
@@ -3265,15 +3510,17 @@ and return one of the non-zero values from "parser.h" 
 #define MG_EUNK		1		/* unknown entity */
 #define MG_EARGC		2		/* wrong number of arguments */
 #define MG_ETYPE		3		/* argument type error */
-#define MG_EILL				4		/* illegal argument value */
+#define MG_EILL			4		/* illegal argument value */
 #define MG_EUNDEF		5		/* undefined reference */
 #define MG_ENOFILE		6		/* cannot open input file */
 #define MG_EINCL		7		/* error in included file */
 #define MG_EMEM		8		/* out of memory */
 #define MG_ESEEK		9		/* file seek error */
 #define MG_EBADMAT	10		/* bad material specification */
+#define MG_ELINE		11		/* input line too long */
+#define MG_ECNTXT		12		/* unmatched context close */
 
-#define MG_NERRS	11
+#define MG_NERRS		13
 .DE
 If it is inappropriate to send output to standard error, the calling
 program should use the routines listed under
@@ -3357,7 +3604,10 @@ The
 function reads the next input line from the current file,
 returning the number of characters in the line, or zero if the
 end of file is reached or there is a file error.
-The function skips over escaped newlines, and keeps track of the
+If the value returned equals MG_MAXLINE-1,
+then the input line was too long, and you
+should return an MG_ELINE error.
+The function keeps track of the
 line number in the current file context
 .I mg_file,
 which also contains the line that was read.
@@ -3677,6 +3927,7 @@ typedef FLOAT  FVECT[3];	/* a 3-d real vector */
 
 typedef struct {
 	int	clock;			/* incremented each change -- resettable */
+	char	*client_data;	/* pointer to private client data */
 	FVECT	p, n;		/* point and normal */
 } C_VERTEX;		/* vertex context */
 .DE
@@ -3693,13 +3944,19 @@ To link identical vertices, one must also check that t
 transform has not changed, which is uniquely identified by the
 global
 .I xf_context->xid
-variable, but only if one is using the parser libraries transform
+variable, but only if one is using the parser library's transform
 handler.
 (See the
 .I xf_handler
 page.)\0
+The
+.I client_data
+pointer may be used to index private application data for vertex
+linking, etc.
+This pointer is initialized to NULL when the context is created,
+and otherwise ignored by the parser library.
 .LP
-It is possible but not recommended to alter the contents of the
+It is possible but not recommended to alter the shared contents of the
 vertex structure returned by
 .I c_getvert.
 Normally it is read during the
@@ -3820,6 +4077,7 @@ structure, defined in "parser.h" as:
 
 typedef struct {
 	int	clock;			/* incremented each change */
+	char	*client_data;	/* pointer to private client data */
 	short	flags;			/* what's been set */
 	short	ssamp[C_CNSS];	/* spectral samples, min wl to max */
 	long	ssum;			/* straight sum of spectral values */
@@ -3835,6 +4093,11 @@ desired.
 This is a convenient way to keep track of whether or not a color has
 changed since its last use.
 The
+.I client_data
+pointer may be used to index private application data.
+This pointer is initialized to NULL when the context is created,
+and otherwise ignored by the parser library.
+The
 .I flags
 member indicates which color representations have been assigned,
 and is an inclusive OR of one or more of the following:
@@ -3979,6 +4242,7 @@ structure, defined in "parser.h" as:
 
 typedef struct {
 	int	clock;		/* incremented each change -- resettable */
+	char	*client_data;	/* pointer to private client data */
 	int	sided;		/* 1 if surface is 1-sided, 0 for 2-sided */
 	float	nr, ni;		/* index of refraction, real and imaginary */
 	float	rd;		/* diffuse reflectance */
@@ -4002,6 +4266,11 @@ material field entity, and may be reset by the calling
 desired.
 This is a convenient way to keep track of whether or not a material has
 changed since its last use.
+The
+.I client_data
+pointer may be used to index private application data.
+This pointer is initialized to NULL when the context is created,
+and otherwise ignored by the parser library.
 .LP
 All reflectance and transmittance values correspond to normal
 incidence, and may vary as a function of angle depending on the
@@ -4424,7 +4693,7 @@ familiar Gaussian model of MGF.
 The hardest part is translating the specular power to a roughness value.
 For this, we recommend the following approximation:
 .IP
-roughness = 0.6/sqrt(specular_power)
+roughness = sqrt(2/specular_power)
 .LP
 It is not a perfect correlation, but it is about as close as one can get.
 .NH 3