cv/mgflib/readme.txt

                MGF PACKAGE DESCRIPTION
                SCCSid "$SunId$ LBL"

This package includes a description and parser for a new scene
description standard, called for the lack of a better name, MGF
for Materials and Geometry Format.  It was developed by Greg
Ward of the Lawrence Berkeley Laboratory <[email protected]> with
help and advice from Rob Shakespeare of Indiana University
<[email protected]>, Ian Ashdown of Ledalite Corporation
<[email protected]> and Holly Rushmeier of the National
Institute for Standards and Technology <[email protected]>.

The language itself is described in the file "spec.txt", and
the included Makefile should make building the parser library
fairly straightforward on most systems.  What's left then, is
explaining the why and how of using this package.

The initial purpose of developing a scene description standard
was for inclusion in the Illumination Engineering Society's (IES)
standard data representation for luminaires.  It occurred to us
early on that such a standard might have broader applications,
so an effort was made to create a fairly general description
language, while keeping it as simple as possible for the people
who have to create descriptions with it as well as the programmers
who have to support it.

Why create a new standard rather than exploiting an existing one?
Some of the rationale for our decision is explained at the end of
the specification document, but it mostly boils down to materials.
As easy as it is to describe physically valid materials, most
scene description languages cannot do it.  The material specification
included in the MGF standard may not be perfect, but at least it's
physically plausible.  Furthermore, we are committed to making any
future modifications to the standard backwards-compatible -- a rather
tricky proposition.

This takes us to the how of supporting this new standard.  The basic
approach is to use the standard parser, which does a lot of the work
in supporting the language itself.  The programmer tells the parser
which entities it will support, and the parser does the rest.
That way, it isn't necessary to modify the program when a new version
of the standard comes out; all one has to do is link to the new
standard's parser.  (The include file will change as well, so it's
not QUITE that simple, but close.)

There are two ways to support the language, by linking the parser to
the program itself, or by linking the parser to a translator program
that expresses MGF entities in the native scene description format.
The differences in the two approaches are slight, and we will mention
them following a general explanation of the parser and support library.

The Parser
==========
The MGF parser is written in ANSI-C (though the -DNOPROTO flag may be
used to get back K&R compatibility).  All of the declarations and
definitions needed are in the single include file "parser.h".  This
file is a good place to look for details on using the various support
routines as well.  The parser itself is parser.c, though it relies for
some translations on other C modules.  These same support routines will
no doubt be useful for applications programmers, and we will explain
some of them in the following sections.

Initializing the parser is the most important part of writing an MGF
program, and it is done through the mg_ehand array and a call to mg_init.
The global mg_ehand variable is an array of pointers to entity handler
functions.  The arguments to these functions are always the same, an
argument count and an array of argument pointers (ala main).  The return
value for these integer functions is one of the error codes defined in
parser.h, or MG_OK if the entity was handled correctly.  You must
set the appropriate entries for the entities you can support, then call
mg_init to fill in the rest.  Most of the entities you cannot support
will be translated into (approximately) equivalent ones you can.
Entities that have no equivalent (such as color), will be safely
ignored on the input.  If you have specified support for some entities
without offering support to their prerequisites, mg_init will report an
error and exit.

Once the parser has been properly initialized, MGF input files may be
loaded at will with the mg_load call.  This function takes a single
argument, which is the name of the MGF file.  (The NULL pointer may be
used to specify standard input.)  The behavior of the parser in part
depends on input history, so the mg_clear call should be used after
each file if starting fresh is important.  This also frees any data
structures used by the parser, which may be desirable if the program
is going to do something after loading besides exit.

Support Functions
=================
In translating unsupported entities, the parser makes use of a number
of support functions, contained in associated C modules.  The most
important of these are in context.c, which includes three handler
functions that can support all color, material and vertex entities.
To understand what these functions do, it is necessary to know a
little about the MGF language itself, so please familiarize yourself
with it now if you haven't already.  (See the file "spec.txt".)

Context Support
===============
The MGF language defines three named contexts, the current vertex,
the current color and the current material.  (The current color is
used mostly for setting parameters in the current material.)  There
are three handler routines defined in context.c, and they can handle
all entities related to these three contexts.  The simplest way to
support materials, for example, is to initialize the mg_ehand array
such that the MG_E_MATERIAL, MG_E_RD, MG_E_RS, etc. entries all point
to c_hmaterial.  Then, whenever a material is needed, the global
c_cmaterial variable will be pointing to a structure with all the
current settings.  (Note that you would have to also set the color
mg_ehand entries to c_hcolor if you intended to support color
materials.)  A list of related mg_ehand assignments is given below:

        mg_ehand[MG_E_COLOR] = c_hcolor;
        mg_ehand[MG_E_CCT] = c_hcolor;
        mg_ehand[MG_E_CMIX] = c_hcolor;
        mg_ehand[MG_E_CSPEC] = c_hcolor;
        mg_ehand[MG_E_CXY] = c_hcolor;
        mg_ehand[MG_E_ED] = c_hmaterial;
        mg_ehand[MG_E_MATERIAL] = c_hmaterial;
        mg_ehand[MG_E_NORMAL] = c_hvertex;
        mg_ehand[MG_E_POINT] = c_hvertex;
        mg_ehand[MG_E_RD] = c_hmaterial;
        mg_ehand[MG_E_RS] = c_hmaterial;
        mg_ehand[MG_E_SIDES] = c_hmaterial;
        mg_ehand[MG_E_TD] = c_hmaterial;
        mg_ehand[MG_E_TS] = c_hmaterial;
        mg_ehand[MG_E_VERTEX] = c_hvertex;

In addition to the three handler functions, context.c contains a
few support routines that make life simpler.  For vertices, there
is the c_getvertex call, which returns a pointer to a named vertex
structure (or NULL if there is no corresponding definition for the
given name).  This function is needed for support of most surface
entities.  For color support, there is the analogous c_getcolor call,
and the c_ccvt routine, which is used to convert from one color
representation to another (e.g.  spectral color to xy chromaticity
coordinates).  Also, there is a function called c_isgrey, which
simply returns 1 or 0 based on whether the passed color structure
is close to grey or not.  Finally, there is the c_clearall routine,
which clears and frees all context data structures, and is the
principal action of the parser's mg_clear function.

Transform Support
=================
If your program is supporting any geometry at all (and what would be
the point if it wasn't?) you will need to support the transform
entity (MG_E_XF).  This would be tricky, if it weren't for the support
routines provided, which make the task fairly painless.  First, there
is the transform handler itself, xf_handler.  Just set the MG_E_XF
entry of the mg_ehand array to this function.  Then, anytime you want
to transform something, call one of the associated functions, xf_xfmpoint,
xf_xfmvect, xf_rotvect or xf_scale.  These functions transform a 3-D
point, 3-D vector (without translation), rotate a 3-D vector (without
scaling) and scale a floating-point value, respectively.

Object Support
==============
The MGF language includes a single entity for naming objects, MG_E_OBJECT.
It is mostly provided as a convenience for the user, so that individual
geometric parts may be easily identified.  Although supporting this entity
directly is possible, it's hierarchical nature requires maintaining a stack
of object names.  The object handler in object.c provides this functionality.
Simply set the MG_E_OBJECT entry of the mg_ehand array to obj_handler,
and the current object name list will be kept in the global array obj_name.
The number of names is stored in the global obj_nnames variable.  To clear
this array (freeing any memory used in the process), call obj_clear.

Loading vs. Translating
=======================
As mentioned in the introduction, the parser may be used either to load
data into a rendering program directly, or to get MGF input for translation
to another file format.  In either case, the procedure is nearly identical.
The only important difference is what you do with the parser data structures
after loading.  For a translator, this is not an issue, but rendering
programs usually need all the memory they can get.  Therefore, once the
input process is complete, you should call the mg_clear function to free
the parser data structures and return to an initialized state (i.e. it
is never necessary to recall the mg_init routine).

Also, if you use some of the support functions, you should call their
specific clearing functions.  For the transform module, the call is
xf_clear.  For the object support module, the call is obj_clear.  The
context routines use the c_clearall function, but this is actually
called by mg_clear, so calling it again is unnecessary.

Linking Vertices
================
Although the MGF language was designed with linking vertices in mind,
there are certain aspects which make this goal more challenging.
Specifically, the ability to redefine values for a previously named
vertex is troublesome for the programmer, since the same vertex can
have different values at different points in the input.  Likewise, the
effect of the transform entity on surfaces rather than vertices means
that the same named vertex can appear in many positions.

It is not possible to use the parser data structures directly for
linking vertices, but we've taken a couple of steps in the support
routines to make the task of organizing your own data structures a
little easier.  First, there is a clock member in the C_VERTEX
structure that is incremented on each change.  (The same member is
contained in the C_COLOR and C_MATERIAL structures.)  Second, the
current transform (pointed to by xf_context) contains a unique
identifier, xf_context->xid.  This is a long integer that will be
different for each unique transform.  (It is actually a hash key on the
transformation matrix, and there is about 1 chance in 2 billion that
two different matrices will hash to the same value.  Is this a bug?
I guess it depends on how long the programmer lives -- or vice versa.)

There are two ways to use of this additional information.  One
is to record the vertex clock value along with it's id and the
current xf_context->xid value.  If another vertex comes along with
the same name, but one of these two additional values fails to match,
then it (probably) is a different vertex.  Alternatively, one can reset
the clock member every time a new vertex is stored.  That way, it is
only necessary to check the clock against zero rather than storing this
value along with the vertex name and transform id.  If the name and
transform are the same and the clock is zero, then it's the same vertex
as last time.

Yet another approach is to ignore the parser structures entirely and
focus on the actual vertex values.  After all, the user is not compelled
to reuse the same vertex names for the same points.  It is just as likely
that the same vertices will appear under different names, so that none
of the above would help to merge them.  The most sure-fire approach to
linking identical vertices is therefore to hash the point and normal
values directly and use the functions in lookup.c to associate them.
You will have to write your own hash function, and we recommend making
one that allows a little slop so that nearly identical points hash to
the same value.

Examples
========
Two example translator programs are included with this package.

The simplest is a translator from MGF to MGF called mgfilt.c, which
produces on the standard output only those entities from the standard
input that are supported according to the first command line argument.
For example, one could remove everything but the raw, flat polygonal
geometry with the following command:

        mgfilt v,p,f,xf any.mgf > faces.mgf

Note that the xf entity must also be included, for its support is
required by all geometric entities.

The second translator converts from MGF to the Radiance scene description
language, and is a more practical example of parser use.  Unfortunately,
we did not include all of the support functions required by this translator,
so it serves as a source code example only.  If you wish to get the rest
of it because you intend to run it, contact Greg Ward <[email protected]>
and he'll be happy to provide you with the missing pieces.

Copyright
=========
At this point, the legal issues related to this parser have not been
worked out.  The intent is to offer it free of charge to all those who
wish to use it (with no guarantees, of course).  However, we may decide
that copyright protections are necessary to prevent unauthorized versions
of the parser, which do not properly support the MGF standard, from
getting spread around.  Since this is a pre-release, we trust that you
will not share it with anyone without getting our permission first.

Questions
=========
Questions should be directed to Greg Ward <[email protected]>, who will be
happy to offer any reasonable assistance in using this standard.  (Greg's
telephone is 1-510-486-4757, fax 1-510-486-4089.)
Revision:	1.6
Committed:	Tue Mar 7 14:53:29 1995 UTC (30 years, 7 months ago) by greg
Content type:	text/plain
Branch:	MAIN
Changes since 1.5:	+4 -3 lines
Log Message:	added cct entity
#	User	Rev	Content
1	greg	1.1	MGF PACKAGE DESCRIPTION
2			SCCSid "$SunId$ LBL"
3
4			This package includes a description and parser for a new scene
5			description standard, called for the lack of a better name, MGF
6			for Materials and Geometry Format. It was developed by Greg
7			Ward of the Lawrence Berkeley Laboratory <[email protected]> with
8			help and advice from Rob Shakespeare of Indiana University
9			<[email protected]>, Ian Ashdown of Ledalite Corporation
10			<[email protected]> and Holly Rushmeier of the National
11			Institute for Standards and Technology <[email protected]>.
12
13			The language itself is described in the file "spec.txt", and
14			the included Makefile should make building the parser library
15			fairly straightforward on most systems. What's left then, is
16			explaining the why and how of using this package.
17
18			The initial purpose of developing a scene description standard
19			was for inclusion in the Illumination Engineering Society's (IES)
20			standard data representation for luminaires. It occurred to us
21			early on that such a standard might have broader applications,
22			so an effort was made to create a fairly general description
23			language, while keeping it as simple as possible for the people
24			who have to create descriptions with it as well as the programmers
25			who have to support it.
26
27			Why create a new standard rather than exploiting an existing one?
28			Some of the rationale for our decision is explained at the end of
29			the specification document, but it mostly boils down to materials.
30			As easy as it is to describe physically valid materials, most
31			scene description languages cannot do it. The material specification
32			included in the MGF standard may not be perfect, but at least it's
33			physically plausible. Furthermore, we are committed to making any
34			future modifications to the standard backwards-compatible -- a rather
35			tricky proposition.
36
37			This takes us to the how of supporting this new standard. The basic
38			approach is to use the standard parser, which does a lot of the work
39			in supporting the language itself. The programmer tells the parser
40			which entities it will support, and the parser does the rest.
41			That way, it isn't necessary to modify the program when a new version
42			of the standard comes out; all one has to do is link to the new
43			standard's parser. (The include file will change as well, so it's
44			not QUITE that simple, but close.)
45
46			There are two ways to support the language, by linking the parser to
47			the program itself, or by linking the parser to a translator program
48			that expresses MGF entities in the native scene description format.
49	greg	1.3	The differences in the two approaches are slight, and we will mention
50	greg	1.1	them following a general explanation of the parser and support library.
51
52			The Parser
53			==========
54			The MGF parser is written in ANSI-C (though the -DNOPROTO flag may be
55			used to get back K&R compatibility). All of the declarations and
56			definitions needed are in the single include file "parser.h". This
57			file is a good place to look for details on using the various support
58			routines as well. The parser itself is parser.c, though it relies for
59			some translations on other C modules. These same support routines will
60			no doubt be useful for applications programmers, and we will explain
61			some of them in the following sections.
62
63			Initializing the parser is the most important part of writing an MGF
64			program, and it is done through the mg_ehand array and a call to mg_init.
65			The global mg_ehand variable is an array of pointers to entity handler
66	greg	1.5	functions. The arguments to these functions are always the same, an
67	greg	1.1	argument count and an array of argument pointers (ala main). The return
68			value for these integer functions is one of the error codes defined in
69			parser.h, or MG_OK if the entity was handled correctly. You must
70			set the appropriate entries for the entities you can support, then call
71			mg_init to fill in the rest. Most of the entities you cannot support
72			will be translated into (approximately) equivalent ones you can.
73			Entities that have no equivalent (such as color), will be safely
74			ignored on the input. If you have specified support for some entities
75			without offering support to their prerequisites, mg_init will report an
76			error and exit.
77
78			Once the parser has been properly initialized, MGF input files may be
79			loaded at will with the mg_load call. This function takes a single
80			argument, which is the name of the MGF file. (The NULL pointer may be
81			used to specify standard input.) The behavior of the parser in part
82			depends on input history, so the mg_clear call should be used after
83			each file if starting fresh is important. This also frees any data
84			structures used by the parser, which may be desirable if the program
85			is going to do something after loading besides exit.
86
87			Support Functions
88			=================
89			In translating unsupported entities, the parser makes use of a number
90			of support functions, contained in associated C modules. The most
91			important of these are in context.c, which includes three handler
92			functions that can support all color, material and vertex entities.
93			To understand what these functions do, it is necessary to know a
94			little about the MGF language itself, so please familiarize yourself
95			with it now if you haven't already. (See the file "spec.txt".)
96
97			Context Support
98			===============
99			The MGF language defines three named contexts, the current vertex,
100			the current color and the current material. (The current color is
101			used mostly for setting parameters in the current material.) There
102			are three handler routines defined in context.c, and they can handle
103			all entities related to these three contexts. The simplest way to
104			support materials, for example, is to initialize the mg_ehand array
105			such that the MG_E_MATERIAL, MG_E_RD, MG_E_RS, etc. entries all point
106			to c_hmaterial. Then, whenever a material is needed, the global
107			c_cmaterial variable will be pointing to a structure with all the
108			current settings. (Note that you would have to also set the color
109			mg_ehand entries to c_hcolor if you intended to support color
110	greg	1.5	materials.) A list of related mg_ehand assignments is given below:
111	greg	1.1
112	greg	1.5	mg_ehand[MG_E_COLOR] = c_hcolor;
113	greg	1.6	mg_ehand[MG_E_CCT] = c_hcolor;
114	greg	1.5	mg_ehand[MG_E_CMIX] = c_hcolor;
115			mg_ehand[MG_E_CSPEC] = c_hcolor;
116			mg_ehand[MG_E_CXY] = c_hcolor;
117			mg_ehand[MG_E_ED] = c_hmaterial;
118			mg_ehand[MG_E_MATERIAL] = c_hmaterial;
119			mg_ehand[MG_E_NORMAL] = c_hvertex;
120			mg_ehand[MG_E_POINT] = c_hvertex;
121			mg_ehand[MG_E_RD] = c_hmaterial;
122			mg_ehand[MG_E_RS] = c_hmaterial;
123			mg_ehand[MG_E_SIDES] = c_hmaterial;
124			mg_ehand[MG_E_TD] = c_hmaterial;
125			mg_ehand[MG_E_TS] = c_hmaterial;
126			mg_ehand[MG_E_VERTEX] = c_hvertex;
127
128	greg	1.1	In addition to the three handler functions, context.c contains a
129			few support routines that make life simpler. For vertices, there
130			is the c_getvertex call, which returns a pointer to a named vertex
131			structure (or NULL if there is no corresponding definition for the
132			given name). This function is needed for support of most surface
133			entities. For color support, there is the analogous c_getcolor call,
134			and the c_ccvt routine, which is used to convert from one color
135			representation to another (e.g. spectral color to xy chromaticity
136			coordinates). Also, there is a function called c_isgrey, which
137			simply returns 1 or 0 based on whether the passed color structure
138			is close to grey or not. Finally, there is the c_clearall routine,
139			which clears and frees all context data structures, and is the
140	greg	1.5	principal action of the parser's mg_clear function.
141	greg	1.1
142			Transform Support
143			=================
144			If your program is supporting any geometry at all (and what would be
145			the point if it wasn't?) you will need to support the transform
146			entity (MG_E_XF). This would be tricky, if it weren't for the support
147			routines provided, which make the task fairly painless. First, there
148			is the transform handler itself, xf_handler. Just set the MG_E_XF
149			entry of the mg_ehand array to this function. Then, anytime you want
150			to transform something, call one of the associated functions, xf_xfmpoint,
151			xf_xfmvect, xf_rotvect or xf_scale. These functions transform a 3-D
152			point, 3-D vector (without translation), rotate a 3-D vector (without
153			scaling) and scale a floating-point value, respectively.
154
155	greg	1.2	Object Support
156			==============
157			The MGF language includes a single entity for naming objects, MG_E_OBJECT.
158			It is mostly provided as a convenience for the user, so that individual
159			geometric parts may be easily identified. Although supporting this entity
160			directly is possible, it's hierarchical nature requires maintaining a stack
161			of object names. The object handler in object.c provides this functionality.
162			Simply set the MG_E_OBJECT entry of the mg_ehand array to obj_handler,
163			and the current object name list will be kept in the global array obj_name.
164			The number of names is stored in the global obj_nnames variable. To clear
165			this array (freeing any memory used in the process), call obj_clear.
166	greg	1.3
167			Loading vs. Translating
168			=======================
169			As mentioned in the introduction, the parser may be used either to load
170			data into a rendering program directly, or to get MGF input for translation
171			to another file format. In either case, the procedure is nearly identical.
172			The only important difference is what you do with the parser data structures
173			after loading. For a translator, this is not an issue, but rendering
174			programs usually need all the memory they can get. Therefore, once the
175			input process is complete, you should call the mg_clear function to free
176			the parser data structures and return to an initialized state (i.e. it
177			is never necessary to recall the mg_init routine).
178
179			Also, if you use some of the support functions, you should call their
180			specific clearing functions. For the transform module, the call is
181			xf_clear. For the object support module, the call is obj_clear. The
182			context routines use the c_clearall function, but this is actually
183			called by mg_clear, so calling it again is unnecessary.
184
185			Linking Vertices
186			================
187			Although the MGF language was designed with linking vertices in mind,
188			there are certain aspects which make this goal more challenging.
189			Specifically, the ability to redefine values for a previously named
190			vertex is troublesome for the programmer, since the same vertex can
191			have different values at different points in the input. Likewise, the
192			effect of the transform entity on surfaces rather than vertices means
193			that the same named vertex can appear in many positions.
194
195			It is not possible to use the parser data structures directly for
196			linking vertices, but we've taken a couple of steps in the support
197			routines to make the task of organizing your own data structures a
198			little easier. First, there is a clock member in the C_VERTEX
199			structure that is incremented on each change. (The same member is
200			contained in the C_COLOR and C_MATERIAL structures.) Second, the
201			current transform (pointed to by xf_context) contains a unique
202			identifier, xf_context->xid. This is a long integer that will be
203			different for each unique transform. (It is actually a hash key on the
204			transformation matrix, and there is about 1 chance in 2 billion that
205			two different matrices will hash to the same value. Is this a bug?
206			I guess it depends on how long the programmer lives -- or vice versa.)
207
208			There are two ways to use of this additional information. One
209			is to record the vertex clock value along with it's id and the
210			current xf_context->xid value. If another vertex comes along with
211			the same name, but one of these two additional values fails to match,
212			then it (probably) is a different vertex. Alternatively, one can reset
213			the clock member every time a new vertex is stored. That way, it is
214			only necessary to check the clock against zero rather than storing this
215			value along with the vertex name and transform id. If the name and
216			transform are the same and the clock is zero, then it's the same vertex
217			as last time.
218
219			Yet another approach is to ignore the parser structures entirely and
220			focus on the actual vertex values. After all, the user is not compelled
221			to reuse the same vertex names for the same points. It is just as likely
222			that the same vertices will appear under different names, so that none
223			of the above would help to merge them. The most sure-fire approach to
224			linking identical vertices is therefore to hash the point and normal
225			values directly and use the functions in lookup.c to associate them.
226	greg	1.4	You will have to write your own hash function, and we recommend making
227	greg	1.3	one that allows a little slop so that nearly identical points hash to
228			the same value.
229	greg	1.2
230	greg	1.1	Examples
231			========
232			Two example translator programs are included with this package.
233
234			The simplest is a translator from MGF to MGF called mgfilt.c, which
235			produces on the standard output only those entities from the standard
236	greg	1.6	input that are supported according to the first command line argument.
237			For example, one could remove everything but the raw, flat polygonal
238	greg	1.1	geometry with the following command:
239
240	greg	1.6	mgfilt v,p,f,xf any.mgf > faces.mgf
241	greg	1.1
242			Note that the xf entity must also be included, for its support is
243			required by all geometric entities.
244
245			The second translator converts from MGF to the Radiance scene description
246			language, and is a more practical example of parser use. Unfortunately,
247			we did not include all of the support functions required by this translator,
248			so it serves as a source code example only. If you wish to get the rest
249			of it because you intend to run it, contact Greg Ward <[email protected]>
250			and he'll be happy to provide you with the missing pieces.
251
252			Copyright
253			=========
254			At this point, the legal issues related to this parser have not been
255	greg	1.2	worked out. The intent is to offer it free of charge to all those who
256	greg	1.1	wish to use it (with no guarantees, of course). However, we may decide
257			that copyright protections are necessary to prevent unauthorized versions
258	greg	1.4	of the parser, which do not properly support the MGF standard, from
259			getting spread around. Since this is a pre-release, we trust that you
260			will not share it with anyone without getting our permission first.
261	greg	1.1
262			Questions
263			=========
264			Questions should be directed to Greg Ward <[email protected]>, who will be
265			happy to offer any reasonable assistance in using this standard. (Greg's
266			telephone is 1-510-486-4757, fax 1-510-486-4089.)