ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/src/cv/mgflib/mgfdoc.tr
(Generate patch)

Comparing ray/src/cv/mgflib/mgfdoc.tr (file contents):
Revision 1.10 by greg, Wed Nov 29 16:45:15 1995 UTC vs.
Revision 1.19 by gregl, Thu Oct 16 11:42:25 1997 UTC

# Line 5 | Line 5
5   .vs 12
6   .nr PD .5v
7   .ds LF MGF
8 < .ds RF Version 1.0
9 < .DA May 1995
8 > .ds RF Version 1.1
9 > .\" !Remember to update date on each modification!
10 > .DA February 1996
11   .TL
12   The Materials and Geometry Format
13   .AU
# Line 42 | Line 43 | and sample scenes and objects at the web site,
43   "http://radsite.lbl.gov/mgf/HOME.html".
44   .RE
45   .LP
46 < The standard parser provides both immediate and a long-term
46 > The standard parser provides both immediate and long-term
47   benefits, since it presents a programming interface that is more
48   stable even than the language itself.
49   Unlike AutoCAD DXF and other de facto standards, a change to the
# Line 232 | Line 233 | p      x y z   set point position for current vertex
233   n       dx dy dz        set surface normal for current vertex
234   _       _       _
235   f       v1 v2 v3 ...    polygon using current material, spec. vertices
236 + fh      v1 v2 v3 - ...  face with explicit holes
237   sph     vc radius       sphere
238   cyl     v1 radius v2    truncated right cylinder (open-ended)
239   cone    v1 rad1 v2 rad2 truncated right cone (open-ended)
# Line 277 | Line 279 | Context        Cntl. Entity    Default Value   Field Entities  Affe
279   =       =       =       =       =
280   Object  o       -       -       -
281   Transform       xf      -       -       T{
282 < f, sph, cyl, cone,
282 > f, fh, sph, cyl, cone,
283   ring, torus, prism
284   T}
285   Material        m       2-sided black   T{
286   sides, rd, td,
287 < ed, rs, ts
287 > ed, rs, ts, ir
288   T}      T{
289 < f, sph, cyl, cone,
289 > f, fh, sph, cyl, cone,
290   ring, torus, prism
291   T}
292   Color   c       neutral grey    T{
# Line 296 | Line 298 | Vertex v       T{
298   (0,0,0),
299   no normal
300   T}      p, n    T{
301 < f, sph, cyl, cone,
301 > f, fh, sph, cyl, cone,
302   ring, torus, prism
303   T}
304   .TE
# Line 815 | Line 817 | Geometry
817   .TS
818   lw(.75i) lw(1.75i) lw(3i).
819   f       v1 v2 v3 ...    polygon using current material, spec. vertices
820 + fh      v1 v2 v3 - ...  face with explicit holes
821   sph     vc radius       sphere
822   cyl     v1 radius v2    truncated right cylinder (open-ended)
823   cone    v1 rad1 v2 rad2 truncated right cone (open-ended)
# Line 1674 | Line 1677 | EXAMPLE
1677   # A 100-watt incandescent bulb (1600 lumens) modeled as a sphere
1678   m
1679          c
1680 <        cct 3000
1680 >                cct 3000
1681          ed 87712
1682   v cent =
1683          p 0 0 0
# Line 1900 | Line 1903 | and
1903   require a normal direction.
1904   An
1905   .UL f
1906 + or
1907 + .UL fh
1908   entity will interpolate vertex normals if given, and
1909   use the polygon plane normal otherwise.
1910   See the
# Line 1939 | Line 1944 | SEE ALSO
1944   .UL cone,
1945   .UL cyl,
1946   .UL f,
1947 + .UL fh,
1948   .UL n,
1949   .UL p,
1950   .UL prism,
# Line 1983 | Line 1989 | SEE ALSO
1989   .UL cone,
1990   .UL cyl,
1991   .UL f,
1992 + .UL fh,
1993   .UL n,
1994   .UL prism,
1995   .UL ring,
# Line 2029 | Line 2036 | xf
2036   SEE ALSO
2037   .LP
2038   .UL f,
2039 + .UL fh,
2040   .UL p,
2041   .UL prism,
2042   .UL ring,
# Line 2068 | Line 2076 | when normals are used.
2076   Also, specified normals should point in the general direction of the
2077   surface for best results.
2078   .LP
2079 < There is no explicit representation of holes in MGF.  A hole must be
2080 < represented implicitly by connecting vertices to form "seams."  For
2079 > There is no explicit representation of holes in this entity, but see
2080 > the
2081 > .UL fh
2082 > entity for an alternative specification.
2083 > .LP
2084 > A hole may be represented implicitly in a face entity
2085 > by connecting vertices to form "seams."
2086 > For
2087   example, a wall with a window in it might look as shown in Figure 1.
2088   In many systems, the wall itself would be represented with the first
2089   list of vertices, (v1,v2,v3,v4) and the hole associated with that
2090 < wall as a second set of vertices (v5,v6,v7,v8).  In MGF, we must
2090 > wall as a second set of vertices (v5,v6,v7,v8).
2091 > Using the face entity, we must
2092   give the whole thing as a single polygon, connecting the vertices so
2093   as to create a "seam," as shown in Figure 2.
2094 < This could be written in MGF as "f v1 v2 v3 v4 v5 v6 v7 v8 v5 v4".
2094 > This could be written as "f v1 v2 v3 v4 v5 v6 v7 v8 v5 v4".
2095   .LP
2096   It is very important that the order of the hole be opposite to the
2097   order of the outer perimeter, otherwise the polygon will be
# Line 2125 | Line 2140 | SEE ALSO
2140   .LP
2141   .UL cone,
2142   .UL cyl,
2143 + .UL fh,
2144   .UL m,
2145   .UL prism,
2146   .UL ring,
2147   .UL sph,
2148   .UL torus,
2149   .UL v
2150 + .ds RH FH
2151 + .bp
2152 + .SH
2153 + NAME
2154 + .LP
2155 + fh - create a polygonal face with explicit holes
2156 + .SH
2157 + SYNOPSIS
2158 + .LP
2159 + .B fh
2160 + .I "p1 p2 ... - h1.1 h1.2 ... - h2.1 h2.2 ..."
2161 + .SH
2162 + DESCRIPTION
2163 + .LP
2164 + Create a polygonal face with optional holes made of the current material.
2165 + The first contour is the outer perimeter, with vertices given in
2166 + counter-clockwise order as seen from the front side (the same as the
2167 + .UL f
2168 + entity).
2169 + A hole is indicated by a hyphen ('-') followed by the hole's
2170 + vertices, given in clockwise order as seen from the front side.
2171 + Multiple hole contours are separated by additional hyphens.
2172 + There must be at least three vertices for each contour, and the
2173 + last vertex is implicitly connected to the first.
2174 + If any vertex is undefined, an error will result.
2175 + .LP
2176 + If any vertices have associated surface normals, they will be used
2177 + instead of the average plane normal, though it is safest to specify
2178 + either all normals or no normals, and to stick with triangles
2179 + when normals are used.
2180 + Also, specified normals should point in the general direction of the
2181 + surface for best results.
2182 + .LP
2183 + Vertices should not be shared between any two contours.
2184 + I.e., a hole should not share a vertex or edge with the perimeter or
2185 + another hole, or incorrect rendering may result.
2186 + .SH
2187 + EXAMPLE
2188 + .DS
2189 + # Make a wall with a window using an explicit hole.
2190 + # (See Figures 1 and 2.)
2191 + fh v1 v2 v3 v4 - v5 v6 v7 v8
2192 + .DE
2193 + .SH
2194 + SEE ALSO
2195 + .LP
2196 + .UL cone,
2197 + .UL cyl,
2198 + .UL f,
2199 + .UL m,
2200 + .UL prism,
2201 + .UL ring,
2202 + .UL sph,
2203 + .UL torus,
2204 + .UL v
2205   .ds RH SPH
2206   .bp
2207   .SH
# Line 2179 | Line 2250 | SEE ALSO
2250   .UL cone,
2251   .UL cyl,
2252   .UL f,
2253 + .UL fh,
2254   .UL m,
2255   .UL prism,
2256   .UL ring,
# Line 2236 | Line 2308 | SEE ALSO
2308   .LP
2309   .UL cone,
2310   .UL f,
2311 + .UL fh,
2312   .UL m,
2313   .UL prism,
2314   .UL ring,
# Line 2308 | Line 2381 | SEE ALSO
2381   .LP
2382   .UL cyl,
2383   .UL f,
2384 + .UL fh,
2385   .UL m,
2386   .UL prism,
2387   .UL ring,
# Line 2374 | Line 2448 | SEE ALSO
2448   .UL cyl,
2449   .UL cone,
2450   .UL f,
2451 + .UL fh,
2452   .UL m,
2453   .UL ring,
2454   .UL sph,
# Line 2430 | Line 2505 | SEE ALSO
2505   .UL cyl,
2506   .UL cone,
2507   .UL f,
2508 + .UL fh,
2509   .UL m,
2510   .UL prism,
2511   .UL sph,
# Line 2490 | Line 2566 | SEE ALSO
2566   .UL cyl,
2567   .UL cone,
2568   .UL f,
2569 + .UL fh,
2570   .UL m,
2571   .UL prism,
2572   .UL ring,
# Line 2501 | Line 2578 | SEE ALSO
2578   .NH
2579   MGF Translators
2580   .LP
2581 < Initially, there are four translators for MGF data, but only
2582 < one of these is distributed with the MGF parser itself,
2583 < .I mgfilt.
2581 > Initially, there are six translators for MGF data, and
2582 > three of these are distributed with the MGF parser itself,
2583 > .I mgfilt,
2584 > .I mgf2inv
2585 > and
2586 > .I 3ds2mgf.
2587   Two of the other translators,
2588   .I mgf2rad
2589   and
# Line 2516 | Line 2596 | package\(dg.
2596   nestor.epfl.ch, or by WWW from
2597   "http://radsite.lbl.gov/radiance/HOME.html"
2598   .FE
2599 < A third translator,
2599 > The sixth translator,
2600   .I mgf2meta,
2601   converts to a 2-dimensional line plot, and is also
2602   distributed with Radiance.
# Line 2533 | Line 2613 | unwanted entities.
2613   In future releases of MGF, this utility will also be handy for
2614   taking new entities and producing older versions of MGF for
2615   translators that have not yet been updated properly.
2616 + .LP
2617 + Mgf2inv converts from MGF to Inventor or VRML format.
2618 + Some information is lost, because these formats do not support
2619 + physical light sources or materials.
2620 + .LP
2621 + 3ds2mgf converts from 3D Studio binary format to MGF.
2622 + Care must be taken to correct for errors in the material descriptions,
2623 + since 3D Studio is completely non-physical.
2624   .ds LH Translators
2625   .ds RH MGFILT
2626   .bp
# Line 2595 | Line 2683 | mgfilt f,v,p,xf input.mgf > flatpoly.mgf
2683   .SH
2684   SEE ALSO
2685   .LP
2686 < i, mgf2rad, rad2mgf
2686 > i, mgf2inv, mgf2rad, rad2mgf
2687 > .ds RH MGF2INV
2688 > .bp
2689 > .SH
2690 > NAME
2691 > .LP
2692 > mgf2inv - convert from MGF to Inventor or VRML format
2693 > .SH
2694 > SYNOPSIS
2695 > .LP
2696 > .B mgf2inv
2697 > [
2698 > .B "-1|-2|-vrml"
2699 > ]
2700 > [
2701 > .B input ..
2702 > ]
2703 > .SH
2704 > DESCRIPTION
2705 > .LP
2706 > .I Mgf2inv
2707 > takes one or more MGF input files and converts it to
2708 > Inventor or VRML format.
2709 > If the
2710 > .I \-1
2711 > option is used, then Inventor 1.0 ASCII output is produced.
2712 > If the
2713 > .I \-2
2714 > option is used, then Inventor 2.0 ASCII output is produced.
2715 > (This is the default.)\0
2716 > If the
2717 > .I \-vrml
2718 > option is used, then VRML 1.0 ASCII output is produced.
2719 > .LP
2720 > This converter does not work properly for light sources, since
2721 > the output formats do not support IES-type luminaires with recorded
2722 > distributions.
2723 > Also, some material information may be lost because Inventor lacks
2724 > a physically valid reflectance model.
2725 > .SH
2726 > EXAMPLES
2727 > .LP
2728 > To take an MGF file and convert it to VRML format:
2729 > .IP
2730 > mgf2inv -vrml myscene.mgf > myscene.iv
2731 > .SH
2732 > SEE ALSO
2733 > .LP
2734 > mgf2rad(1), mgfilt(1), 3ds2mgf(1), rad2mgf(1)
2735 > .ds RH 3DS2MGF
2736 > .bp
2737 > .SH
2738 > NAME
2739 > .LP
2740 > 3ds2mgf - convert 3D Studio binary file to Materials and Geometry Format
2741 > .SH
2742 > SYNOPSIS
2743 > .LP
2744 > .B 3ds2mgf
2745 > .B input
2746 > [
2747 > .B output
2748 > ]
2749 > [
2750 > .B -lMatlib
2751 > ][
2752 > .B -xObjname
2753 > ][
2754 > .B -sAngle
2755 > ][
2756 > .B -aAnimfile
2757 > ][
2758 > .B -fN
2759 > ]
2760 > .SH
2761 > DESCRIPTION
2762 > .LP
2763 > .I 3ds2mgf
2764 > converts a 3D Studio binary scene description
2765 > to the Materials and Geometry Format (MGF).
2766 > If no output file name is given, the input root name
2767 > will be taken as the output root, and an "mgf" extension
2768 > will be added.
2769 > This file will contain any light sources and materials, and an include
2770 > statement for a similarly named file ending in "inc", which will contain
2771 > the MGF geometry of all the translated 3DS meshes.
2772 > .LP
2773 > The MGF material names and properties
2774 > for the surfaces will be those assigned in 3D Studio,
2775 > unless they are named in one or more MGF material libraries given in a
2776 > .I -l
2777 > option.
2778 > .LP
2779 > The
2780 > .I -x
2781 > option may be used to exclude a named object from the output.
2782 > .LP
2783 > The
2784 > .I -s
2785 > option may be used to adjust automatic mesh smoothing such that adjacent
2786 > triangle faces with less than the given angle between them (in degrees)
2787 > will be smoothed.
2788 > A value of zero turns smoothing off.
2789 > The default value is 60 degrees.
2790 > .LP
2791 > The
2792 > .I -a
2793 > option may be used to specify a 3D Studio animation file, and together with the
2794 > .I -f
2795 > option,
2796 > .I 3ds2mgf
2797 > will generate a scene description for the specified frame.
2798 > .LP
2799 > Note that there are no spaces between the options and their arguments.
2800 > .SH
2801 > LIMITATIONS
2802 > .LP
2803 > Obviously, since 3D Studio has no notion of physical materials, the
2804 > translation to MGF material descriptions is very ad hoc, and it will
2805 > usually be necessary to edit the materials and light sources in
2806 > the output file or replace materials with proper entries from a material
2807 > library using the
2808 > .I -l
2809 > option.
2810 > .LP
2811 > With smoothing turned on (i.e., a non-zero value for the
2812 > .I -s
2813 > option), vertices in the MGF output will not be linked in a proper
2814 > mesh for each object.
2815 > This is due to the way the automatic smoothing code was originally
2816 > written, and is too difficult to repair.
2817 > If a good mesh is needed, then smoothing must be turned off.
2818 > .SH
2819 > EXAMPLES
2820 > .LP
2821 > To convert a 3D Studio robot model to MGF without smoothing.
2822 > (Output will be put into "robot.mgf" and "robot.inc".)
2823 > .IP
2824 > 3ds2mgf robot.3ds -s0
2825 > .LP
2826 > To convert a DC10 jet model to MGF using a hand-created material library:
2827 > .IP
2828 > 3ds2mgf dc10.3ds -ldc10mat.mgf
2829 > .SH
2830 > AUTHORS
2831 > .LP
2832 > Steve Anger, Jeff Bowermaster and Greg Ward
2833 > .br
2834 > Extended from 3ds2pov 1.8.
2835 > .SH
2836 > SEE ALSO
2837 > .LP
2838 > mgf2inv(1), mgf2meta(1), mgf2rad(1)
2839   .ds RH MGF2RAD
2840   .bp
2841   .SH
# Line 3270 | Line 3510 | and return one of the non-zero values from "parser.h"
3510   #define MG_EUNK         1               /* unknown entity */
3511   #define MG_EARGC                2               /* wrong number of arguments */
3512   #define MG_ETYPE                3               /* argument type error */
3513 < #define MG_EILL                         4               /* illegal argument value */
3513 > #define MG_EILL                 4               /* illegal argument value */
3514   #define MG_EUNDEF               5               /* undefined reference */
3515   #define MG_ENOFILE              6               /* cannot open input file */
3516   #define MG_EINCL                7               /* error in included file */
# Line 3280 | Line 3520 | and return one of the non-zero values from "parser.h"
3520   #define MG_ELINE                11              /* input line too long */
3521   #define MG_ECNTXT               12              /* unmatched context close */
3522  
3523 < #define MG_NERRS        13
3523 > #define MG_NERRS                13
3524   .DE
3525   If it is inappropriate to send output to standard error, the calling
3526   program should use the routines listed under
# Line 3364 | Line 3604 | The
3604   function reads the next input line from the current file,
3605   returning the number of characters in the line, or zero if the
3606   end of file is reached or there is a file error.
3607 < If the last character read in the input line is not a newline,
3607 > If the value returned equals MG_MAXLINE-1,
3608   then the input line was too long, and you
3609   should return an MG_ELINE error.
3610 < The function skips over escaped newlines, and keeps track of the
3610 > The function keeps track of the
3611   line number in the current file context
3612   .I mg_file,
3613   which also contains the line that was read.
# Line 3687 | Line 3927 | typedef FLOAT  FVECT[3];       /* a 3-d real vector */
3927  
3928   typedef struct {
3929          int     clock;                  /* incremented each change -- resettable */
3930 +        char    *client_data;   /* pointer to private client data */
3931          FVECT   p, n;           /* point and normal */
3932   } C_VERTEX;             /* vertex context */
3933   .DE
# Line 3703 | Line 3944 | To link identical vertices, one must also check that t
3944   transform has not changed, which is uniquely identified by the
3945   global
3946   .I xf_context->xid
3947 < variable, but only if one is using the parser libraries transform
3947 > variable, but only if one is using the parser library's transform
3948   handler.
3949   (See the
3950   .I xf_handler
3951   page.)\0
3952 + The
3953 + .I client_data
3954 + pointer may be used to index private application data for vertex
3955 + linking, etc.
3956 + This pointer is initialized to NULL when the context is created,
3957 + and otherwise ignored by the parser library.
3958   .LP
3959 < It is possible but not recommended to alter the contents of the
3959 > It is possible but not recommended to alter the shared contents of the
3960   vertex structure returned by
3961   .I c_getvert.
3962   Normally it is read during the
# Line 3830 | Line 4077 | structure, defined in "parser.h" as:
4077  
4078   typedef struct {
4079          int     clock;                  /* incremented each change */
4080 +        char    *client_data;   /* pointer to private client data */
4081          short   flags;                  /* what's been set */
4082          short   ssamp[C_CNSS];  /* spectral samples, min wl to max */
4083          long    ssum;                   /* straight sum of spectral values */
# Line 3845 | Line 4093 | desired.
4093   This is a convenient way to keep track of whether or not a color has
4094   changed since its last use.
4095   The
4096 + .I client_data
4097 + pointer may be used to index private application data.
4098 + This pointer is initialized to NULL when the context is created,
4099 + and otherwise ignored by the parser library.
4100 + The
4101   .I flags
4102   member indicates which color representations have been assigned,
4103   and is an inclusive OR of one or more of the following:
# Line 3989 | Line 4242 | structure, defined in "parser.h" as:
4242  
4243   typedef struct {
4244          int     clock;          /* incremented each change -- resettable */
4245 +        char    *client_data;   /* pointer to private client data */
4246          int     sided;          /* 1 if surface is 1-sided, 0 for 2-sided */
4247          float   nr, ni;         /* index of refraction, real and imaginary */
4248          float   rd;             /* diffuse reflectance */
# Line 4012 | Line 4266 | material field entity, and may be reset by the calling
4266   desired.
4267   This is a convenient way to keep track of whether or not a material has
4268   changed since its last use.
4269 + The
4270 + .I client_data
4271 + pointer may be used to index private application data.
4272 + This pointer is initialized to NULL when the context is created,
4273 + and otherwise ignored by the parser library.
4274   .LP
4275   All reflectance and transmittance values correspond to normal
4276   incidence, and may vary as a function of angle depending on the
# Line 4434 | Line 4693 | familiar Gaussian model of MGF.
4693   The hardest part is translating the specular power to a roughness value.
4694   For this, we recommend the following approximation:
4695   .IP
4696 < roughness = 0.6/sqrt(specular_power)
4696 > roughness = sqrt(2/specular_power)
4697   .LP
4698   It is not a perfect correlation, but it is about as close as one can get.
4699   .NH 3

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines