--- ray/src/cv/mgflib/mgfdoc.tr	1996/02/21 14:26:43	1.13
+++ ray/src/cv/mgflib/mgfdoc.tr	1997/10/16 11:42:25	1.19
@@ -233,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)
@@ -278,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{
@@ -297,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
@@ -816,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)
@@ -1675,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
@@ -1901,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
@@ -1940,6 +1944,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL n,
 .UL p,
 .UL prism,
@@ -1984,6 +1989,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL n,
 .UL prism,
 .UL ring,
@@ -2030,6 +2036,7 @@ xf
 SEE ALSO
 .LP
 .UL f,
+.UL fh,
 .UL p,
 .UL prism,
 .UL ring,
@@ -2069,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
@@ -2126,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
@@ -2180,6 +2250,7 @@ SEE ALSO
 .UL cone,
 .UL cyl,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2237,6 +2308,7 @@ SEE ALSO
 .LP
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2309,6 +2381,7 @@ SEE ALSO
 .LP
 .UL cyl,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -2375,6 +2448,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL ring,
 .UL sph,
@@ -2431,6 +2505,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL sph,
@@ -2491,6 +2566,7 @@ SEE ALSO
 .UL cyl,
 .UL cone,
 .UL f,
+.UL fh,
 .UL m,
 .UL prism,
 .UL ring,
@@ -3434,7 +3510,7 @@ 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 */
@@ -3444,7 +3520,7 @@ and return one of the non-zero values from "parser.h" 
 #define MG_ELINE		11		/* input line too long */
 #define MG_ECNTXT		12		/* unmatched context close */
 
-#define MG_NERRS	13
+#define MG_NERRS		13
 .DE
 If it is inappropriate to send output to standard error, the calling
 program should use the routines listed under
@@ -3851,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
@@ -3867,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
@@ -3994,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 */
@@ -4009,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:
@@ -4153,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 */
@@ -4176,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
@@ -4598,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