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

Comparing ray/src/cv/mgflib/readme.txt (file contents):
Revision 1.1 by greg, Sat Jun 25 09:57:52 1994 UTC vs.
Revision 1.8 by greg, Fri Feb 28 20:19:26 2003 UTC

# Line 1 | Line 1
1                  MGF PACKAGE DESCRIPTION
2 <                SCCSid "$SunId$ LBL"
2 >                RCSid "$Id$"
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
# Line 46 | Line 46 | not QUITE that simple, but close.)
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 < The differences in the two approaches are slight, and we will explain
49 > The differences in the two approaches are slight, and we will mention
50   them following a general explanation of the parser and support library.
51  
52   The Parser
# Line 63 | Line 63 | some of them in the following sections.
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 < functions.  The arguments to these functions is always the same, an
66 > functions.  The arguments to these functions are always the same, an
67   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
# Line 107 | Line 107 | to c_hmaterial.  Then, whenever a material is needed,
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 < materials.)
110 > materials.)  A list of related mg_ehand assignments is given below:
111  
112 +        mg_ehand[MG_E_COLOR] = c_hcolor;
113 +        mg_ehand[MG_E_CCT] = c_hcolor;
114 +        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_IR] = c_hmaterial;
119 +        mg_ehand[MG_E_MATERIAL] = c_hmaterial;
120 +        mg_ehand[MG_E_NORMAL] = c_hvertex;
121 +        mg_ehand[MG_E_POINT] = c_hvertex;
122 +        mg_ehand[MG_E_RD] = c_hmaterial;
123 +        mg_ehand[MG_E_RS] = c_hmaterial;
124 +        mg_ehand[MG_E_SIDES] = c_hmaterial;
125 +        mg_ehand[MG_E_TD] = c_hmaterial;
126 +        mg_ehand[MG_E_TS] = c_hmaterial;
127 +        mg_ehand[MG_E_VERTEX] = c_hvertex;
128 +
129   In addition to the three handler functions, context.c contains a
130   few support routines that make life simpler.  For vertices, there
131   is the c_getvertex call, which returns a pointer to a named vertex
# Line 121 | Line 138 | coordinates).  Also, there is a function called c_isgr
138   simply returns 1 or 0 based on whether the passed color structure
139   is close to grey or not.  Finally, there is the c_clearall routine,
140   which clears and frees all context data structures, and is the
141 < principle action of the parser's mg_clear function.
141 > principal action of the parser's mg_clear function.
142  
143   Transform Support
144   =================
# Line 136 | Line 153 | xf_xfmvect, xf_rotvect or xf_scale.  These functions t
153   point, 3-D vector (without translation), rotate a 3-D vector (without
154   scaling) and scale a floating-point value, respectively.
155  
156 + Object Support
157 + ==============
158 + The MGF language includes a single entity for naming objects, MG_E_OBJECT.
159 + It is mostly provided as a convenience for the user, so that individual
160 + geometric parts may be easily identified.  Although supporting this entity
161 + directly is possible, it's hierarchical nature requires maintaining a stack
162 + of object names.  The object handler in object.c provides this functionality.
163 + Simply set the MG_E_OBJECT entry of the mg_ehand array to obj_handler,
164 + and the current object name list will be kept in the global array obj_name.
165 + The number of names is stored in the global obj_nnames variable.  To clear
166 + this array (freeing any memory used in the process), call obj_clear.
167 +
168 + Loading vs. Translating
169 + =======================
170 + As mentioned in the introduction, the parser may be used either to load
171 + data into a rendering program directly, or to get MGF input for translation
172 + to another file format.  In either case, the procedure is nearly identical.
173 + The only important difference is what you do with the parser data structures
174 + after loading.  For a translator, this is not an issue, but rendering
175 + programs usually need all the memory they can get.  Therefore, once the
176 + input process is complete, you should call the mg_clear function to free
177 + the parser data structures and return to an initialized state (i.e. it
178 + is never necessary to recall the mg_init routine).
179 +
180 + Also, if you use some of the support functions, you should call their
181 + specific clearing functions.  For the transform module, the call is
182 + xf_clear.  For the object support module, the call is obj_clear.  The
183 + context routines use the c_clearall function, but this is actually
184 + called by mg_clear, so calling it again is unnecessary.
185 +
186 + Linking Vertices
187 + ================
188 + Although the MGF language was designed with linking vertices in mind,
189 + there are certain aspects which make this goal more challenging.
190 + Specifically, the ability to redefine values for a previously named
191 + vertex is troublesome for the programmer, since the same vertex can
192 + have different values at different points in the input.  Likewise, the
193 + effect of the transform entity on surfaces rather than vertices means
194 + that the same named vertex can appear in many positions.
195 +
196 + It is not possible to use the parser data structures directly for
197 + linking vertices, but we've taken a couple of steps in the support
198 + routines to make the task of organizing your own data structures a
199 + little easier.  First, there is a clock member in the C_VERTEX
200 + structure that is incremented on each change.  (The same member is
201 + contained in the C_COLOR and C_MATERIAL structures.)  Second, the
202 + current transform (pointed to by xf_context) contains a unique
203 + identifier, xf_context->xid.  This is a long integer that will be
204 + different for each unique transform.  (It is actually a hash key on the
205 + transformation matrix, and there is about 1 chance in 2 billion that
206 + two different matrices will hash to the same value.  Is this a bug?
207 + I guess it depends on how long the programmer lives -- or vice versa.)
208 +
209 + There are two ways to use of this additional information.  One
210 + is to record the vertex clock value along with it's id and the
211 + current xf_context->xid value.  If another vertex comes along with
212 + the same name, but one of these two additional values fails to match,
213 + then it (probably) is a different vertex.  Alternatively, one can reset
214 + the clock member every time a new vertex is stored.  That way, it is
215 + only necessary to check the clock against zero rather than storing this
216 + value along with the vertex name and transform id.  If the name and
217 + transform are the same and the clock is zero, then it's the same vertex
218 + as last time.
219 +
220 + Yet another approach is to ignore the parser structures entirely and
221 + focus on the actual vertex values.  After all, the user is not compelled
222 + to reuse the same vertex names for the same points.  It is just as likely
223 + that the same vertices will appear under different names, so that none
224 + of the above would help to merge them.  The most sure-fire approach to
225 + linking identical vertices is therefore to hash the point and normal
226 + values directly and use the functions in lookup.c to associate them.
227 + You will have to write your own hash function, and we recommend making
228 + one that allows a little slop so that nearly identical points hash to
229 + the same value.
230 +
231   Examples
232   ========
233   Two example translator programs are included with this package.
234  
235   The simplest is a translator from MGF to MGF called mgfilt.c, which
236   produces on the standard output only those entities from the standard
237 < input that are supported according to the command line arguments.  For
238 < example, one could remove everything but the raw, flat polygonal
237 > input that are supported according to the first command line argument.
238 > For example, one could remove everything but the raw, flat polygonal
239   geometry with the following command:
240  
241 <        mgfilt v p f xf < any.mgf > faces.mgf
241 >        mgfilt v,p,f,xf any.mgf > faces.mgf
242  
243   Note that the xf entity must also be included, for its support is
244   required by all geometric entities.
# Line 161 | Line 253 | and he'll be happy to provide you with the missing pie
253   Copyright
254   =========
255   At this point, the legal issues related to this parser have not been
256 < considered.  The intent is to offer it free of charge to all those who
256 > worked out.  The intent is to offer it free of charge to all those who
257   wish to use it (with no guarantees, of course).  However, we may decide
258   that copyright protections are necessary to prevent unauthorized versions
259 < of the parser that do not properly support the MGF standard from getting
260 < spread around.  Since this is a pre-release, we trust that you will not
261 < share it with anyone without getting our permission first.
259 > of the parser, which do not properly support the MGF standard, from
260 > getting spread around.  Since this is a pre-release, we trust that you
261 > will not share it with anyone without getting our permission first.
262  
263   Questions
264   =========

Diff Legend

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