--- ray/src/cv/mgflib/spec.txt 1994/06/25 09:46:58 1.1 +++ ray/src/cv/mgflib/spec.txt 2003/02/28 20:19:26 1.9 @@ -1,5 +1,5 @@ MATERIALS AND GEOMETRY FORMAT - SCCSid "$SunId$ LBL" + RCSid "$Id: spec.txt,v 1.9 2003/02/28 20:19:26 greg Exp $" Introduction ============ @@ -27,9 +27,8 @@ current transform and the current object name. Each entity is given by a short keyword, followed by space- or tab- delimited arguments on a single line. A single entity may be extended over multiple lines using a backslash ('\') character right before the -end of line, though no extended line may exceed 512 characters in total -length. (Given the current set of entities, even approaching 80 -characters would be highly unusual.) +end of line, though no extended line may exceed 4096 characters in total +length. Entities and Contexts ===================== @@ -37,24 +36,24 @@ There are three contexts in effect at all times, curre current color and current material. Initially, these contexts are unnamed, and have specific default values. The unnamed vertex is the origin. The unnamed color is neutral gray. The unnamed material is a -perfect absorber. The unnamed contexts may be modified, but those -modifications will not be saved. Thus, reestablishing an unnamed -context always gets its initial default value. To save a new context -or modify an old one, it must first be named. Entities associated with -named contexts (i.e. "v", "c" and "m") may be followed by an identifier -and an equals sign ('='), indicating a new context. If there is no -equals, then the context must already be defined, and the appearance of -the entity merely reestablishes this context. If the context id is -followed by an equals, then a new context is defined, destroying any -previous instance of that context name. Redefining or changing values -of a context does not affect earlier uses of the same name, however. -Contexts are always associated with a name id, which is any non-blank -sequence of printing ASCII characters. An optional template may be -given following the equals, which is a previously defined context to -use as a source of default values for this definition. If no template -is given, then the unnamed context of that type is used to set initial -values. Named contexts continue until the next context definition of -the same type. +perfect (two-sided) absorber. The unnamed contexts may be modified, +but those modifications will not be saved. Thus, reestablishing an +unnamed context always gets its initial default value. To save a new +context or modify an old one, it must first be named. Entities +associated with named contexts (i.e. "v", "c" and "m") may be followed +by an identifier and an equals sign ('='), indicating a new context. +If there is no equals, then the context must already be defined, and +the appearance of the entity merely reestablishes this context. If the +context id is followed by an equals, then a new context is defined, +destroying any previous instance of that context name. Redefining or +changing values of a context does not affect earlier uses of the same +name, however. Contexts are always associated with a name id, which is +any non-blank sequence of printing ASCII characters. An optional +template may be given following the equals, which is a previously +defined context to use as a source of default values for this +definition. If no template is given, then the unnamed context of that +type is used to set initial values. Named contexts continue until the +next context definition of the same type. Hierarchical Contexts ===================== @@ -68,7 +67,8 @@ can be thought of as parts and subparts of an enclosin Note that this is strictly for ease of identification, and has no real meaning as far as the geometric description goes. In contrast, the transform entity is very significant as it determines how enclosing -objects are to be scaled and placed in the final description. +objects are to be scaled and placed in the final description. Hierarchical +contexts may be nested in any way, but should not overlap. Without further ado, here are the proposed entities and their interpretations: @@ -83,19 +83,22 @@ n dx dy dz set surface normal for current vertex 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 o [name] begin/end object context 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 right prism (closed solid) +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 xf [xform] begin/end transformation context @@ -106,6 +109,7 @@ Entities Contexts -------- -------- p, n vertex cxy, cspec, cmix color +sides material rd, td, ed, rs, ts color, material f, sph, cyl, cone, ring, torus, prism material, object, transformation @@ -142,11 +146,12 @@ Rotations are given in degrees counter-clockwise about That is, with the thumb of the right hand pointing in the direction of the axis, rotation follows the curl of the fingers. -The transform command itself is also cumulative, and a transform -command with no arguments is used to return to the previous -condition. It is best if transforms and their end statements -("xf" by itself) are balanced in a file, so that later or enclosing -files are not affected. +The transform command itself is also cumulative, but in the reverse +order. That is, later transformations (i.e. enclosed transformations) +are prepended to existing (i.e. enclosing) ones. A transform command +with no arguments is used to return to the previous condition. It is +necessary that transforms and their end statements ("xf" by itself) be +balanced in a file, so that later or enclosing files are not affected. Transformations apply only to geometric types, e.g. polygons, spheres, etc. Vertices and the components that go into geometry are not directly affected. @@ -157,10 +162,9 @@ Arrays ====== The -a N transform specification causes the following transform arguments to be repeated along with the contents of the included -file N times. (Note that this option is supported only for included -files.) The first instance of the geometry will be in its initial -location; the second instance will be repositioned according to the -named transformation; the third instance will be repositioned by +objects N times. The first instance of the geometry will be in its +initial location; the second instance will be repositioned according +to the named transformation; the third instance will be repositioned by applying this transformation twice, and so on up to N-1 applications. Multi-dimensional arrays may be specified with a single include @@ -207,18 +211,22 @@ saturation. Intensity, such as reflectance or emittan included in the other material parameters. All colors are absolute, e.g. spectral reflectance or transmittance under uniform white light. -A CIE xy chromaticity pair is the most basic color specification. -A full spectrum is the most general specification, and the starting -(i.e. minimum) and ending (i.e. maximum) wavelengths are given along -with a set of evenly spaced values. Wavelengths are given in nanometers, -and must be within the range of 380-780. The spectral values themselves -are located starting at the first wavelength and proceeding at even -increments to the ending wavelength. The values in between will be -interpolated as necessary, so there must be at least two specified points. -The color mixing entity is intended not only for the mixing of named -colors, but also for color specifications using an arbitrary set -of basis functions. The actual totals for spectral and mixing -coefficients is irrelevant, since the results will be normalized. +A CIE xy chromaticity pair is the most basic color specification. A +full spectrum is the most general specification, and the starting (i.e. +minimum) and ending (i.e. maximum) wavelengths are given along with a +set of evenly spaced values. Wavelengths are given in nanometers, and +should be within the range of 380-780. The spectral values themselves, +which can be thought of as relative power density per nanometer, start +at the first wavelength and proceed at even increments to the last +wavelength. The values in between will be interpolated as necessary, +so there must be at least two specified points. The color temperature +entity corresponds to the spectrum of a black body at the specified +temperature (in degrees Kelvin). The color mixing entity is intended +not only for the mixing of named colors, but also for color +specifications using an arbitrary set of basis functions. The mixing +coefficients are in effect relative luminances for each color +"primary." The actual total of the mixing coefficients or spectral +values is irrelevant, since the results will always be normalized. Diffuse emittance is always given in SI units of lumens/meter^2. Note that this is emittance, not exitance, and does not include light reflected or @@ -231,20 +239,35 @@ be scattered. The sum of the diffuse and specular reflectances and transmittances must be strictly less than one (with no negative values, obviously). +These values are assumed to be measured at normal incidence. If an +index of refraction is given, this may modify the balance between +diffuse and specular reflectance at other incident angles. If the +material is one-sided (see below), then it may be a dielectric interface. +In this case, the specular transmittance given is that which would be +measured at normal incidence for a pane of the material 5 mm thick. +This is important for figuring the actual transmittance for non-planar +geometries assuming a uniformly absorbing medium. If the index of +refraction has an imaginary part, then the surface is a metal and this +implies other properties according to physics. The default index of +refraction is that of a vacuum, i.e. (1,0). The object entity establishes a hierarchical context, consisting of this identifier and all those preceding. It has no real meaning except to group the following surfaces up until an empty object statement under a descriptive name for improved file readability. -Surfaces are one-sided, and appear invisible when viewed from the -back side. This means that a transmitting object will affect the -light coming in through the front surface and ignore the characteristics -of the back surface. As long as the characteristics are the same, -the results should be correct. If the rendering technique does not -allow for one-sided surfaces, an approximately correct result can -be obtained for transmitting surfaces by using the square root of -the given tau_s and half the given alpha_t. +Surfaces are two-sided unless the "sides" entity is used to set the +number of sides for a material to one. If a surface is one-sided, +then it appears invisible when viewed from the back side. This means +that a transmitting object will affect the light coming in through the +front surface and ignore the characteristics of the back surface. As +long as the transmission characteristics are the same, the results should +be correct. If the rendering technique does not allow for one-sided +surfaces, an approximately correct result can be obtained for one-sided +transmitting surfaces by using the square root of the given tau_s and +half the given alpha_t. If a rendering technique does not permit +two-sided surfaces, then each surface must be made into two for +full compliance if "sides" is set to 2 (the default). The surface normal of a face is oriented by the right-hand rule. Specifically, the surface normal faces towards the viewer when the @@ -256,7 +279,10 @@ A prism consists of a set of coplanar vertices specify and a length value. The prism will be extruded so that the end-face points outward, unless the length value is negative, in which case the object is extruded in the opposite direction, resulting in inward- -directed surface normals. +directed surface normals. If surface normals are specified for the +vertices, they will be applied to the side faces but not the end +faces, and they must generally point in the appropriate direction +(i.e. in or out depending on whether extrusion is negative or positive). A sphere, cylinder or cone with negative radii is interpreted as having an inward facing surface normal. Otherwise, the normal is assumed