Keyword Arguments Interpretation
===============================================================================
# [anything ...] a comment
o [name] begin/end object context
xf [xform] begin/end transformation context
i pathname [xform] include file (with transformation)
ies pathname [-m f][xform] include IES luminaire (with transformation)
-------------------------------------------------------------------------------
c [id [= [template]]] get/set color context
cxy x y set CIE (x,y) chromaticity for current color
cspec l_min l_max v1 v2 ... set relative spectrum for current color
cct temperature set spectrum based on black body temperature
cmix w1 c1 w2 c2 ... mix named colors to make current color
-------------------------------------------------------------------------------
m [id [= [template]]] get/set material context
sides {1|2} set number of sides for current material
rd rho_d set diffuse reflectance for current material
td tau_d set diffuse transmittance for current material
ed epsilon_d set diffuse emittance for current material
rs rho_s alpha_r set specular reflectance for current material
ts tau_s alpha_t set specular transmittance for current material
ir n_real n_imag set index of refraction for current material
-------------------------------------------------------------------------------
v [id [= [template]]] get/set vertex context
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
sph vc radius sphere
cyl v1 radius v2 truncated right cylinder (open-ended)
cone v1 rad1 v2 rad2 truncated right cone (open-ended)
prism v1 v2 v3 ... length truncated right prism (closed solid)
ring vc rmin rmax circular ring with inner and outer radii
torus vc rmin rmax circular torus with inner and outer radii
-------------------------------------------------------------------------------
Table 1. MGF entities and their arguments. Arguments in brackets are optional. Arguments in curly braces mean one of the given choices must appear. Ellipsis (...) mean that any number of arguments may be given.A context describes the current state of the interpreter, and affects or is affected by certain entities as they are read in. MGF contexts can be divided into two types, hierarchical contexts and named contexts.
Hierarchical contexts are manipulated by a single entity and have an associated "stack" onto which new contexts are "pushed" using the entity. The last context may be "popped" by giving the entity again with no arguments. The two hierarchical contexts in MGF are the current transformation, manipulated with the xf entity, and the current object, manipulated with the o entity.
Context Cntl. Entity Default Value Field Entities Affects =============================================================================== Object o - - - Transform xf - - f, sph, cyl, cone, ring, torus, prism Material m 2-sided black sides, rd, td, f, sph, cyl, ed, rs, ts cone, ring, torus, prism Color c neutral grey cxy, cspec, rd, td, ed, cct, cmix rs, ts Vertex v (0,0,0), p, n f, sph, cyl, no normal cone, ring, torus, prism -------------------------------------------------------------------------------
Table 2. MGF contexts and their related entities and default values.Named contexts in contrast hold sets of values that are swapped in and out one at a time. There are three named contexts in MGF, the current material, the current color and the current vertex. Each one may be associated with an identifier, and one of each is in effect at any given time. Initially, these contexts are unnamed, and invoking an unnamed context always returns to the original (default) values. (See Table 2 for a list of contexts, their related entities and defaults.)
It is easiest to think of a context as a "scratch space" where values are written by some entities and read by others. Naming a context allows us to reestablish the same scratch space later, usually for reference but it can be altered as well. Let us say we wanted to create a smooth blue plastic material with a diffuse reflectance of 20% and a specular reflectance of 4%:
# Establish a new material context called "blue_plastic" m blue_plastic = # Reestablish a previous color context called "blue" c blue # Set the diffuse reflectance, which uses the above color rd .20 # Get the unnamed color context (always starts out grey) c # Set the specular reflectance, which is uncolored rs .04 0 # We're done, the current material context is now "blue_plastic"Note that the above assumes that we have previously defined a color context named "blue". If we forgot to do that, the above description would generate an "undefined" error. The color context affects the material context indirectly because it is read by the specular and diffuse reflectance entities, which are in turn written to the current material. It is not necessary to indent the entities that affect the material definition, but it improves readability. Note also that there is no explicit end to the material definition. As long as a context remains in effect, its contents may be altered by its field entities. This will not affect previous uses of the context, however. For example, a surface entity following the above definition will have the specified color and reflectance, and later changes to the material "blue_plastic" will have no effect on it.
Each of the three named contexts has an associated entity that controls it. The material context is controlled by the m entity, the color context is controlled by the c entity, and the vertex context is controlled by the v entity. There are exactly four forms for each entity. The first form is the keyword by itself, which establishes an unnamed context with predetermined default values. This is a useful way to set values without worrying about saving them for recall later. The second form is to give the keyword with a previously defined name. This reestablishes a prior context for reuse. The third form is to give the keyword with a name followed by an equals sign. (There must be a space between the name and the equals sign, since it is a separate argument.) This establishes a new context and assigns it the same default values as the unnamed context. The fourth and final form gives the keyword followed by a name then an equals then the name of a previous context definition. This establishes a new context for the first name, assigning the values from the second named context rather than the usual defaults. This is a convenient way create an alias or to modify a context under a new name (i.e. "save as").