[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Conventions


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.1 Syntax Common to All OOGL File Formats

Most OOGL object file formats are free-format ASCII -- any amount of white space (blanks, tabs, newlines) may appear between tokens (numbers, key words, etc.). Line breaks are almost always insignificant, with a couple of exceptions as noted. Comments begin with # and continue to the end of the line; they're allowed anywhere a newline is.

Binary formats are also defined for several objects; See section Binary format, and the individual object descriptions.

Typical OOGL objects begin with a key word designating object type, possibly with modifiers indicating presence of color information etc. In some formats the key word is optional, for compatibility with file formats defined elsewhere. Object type is then determined by guessing from the file suffix (if any) or from the data itself.

Key words are case sensitive. Some have optional prefix letters indicating presence of color or other data; in this case the order of prefixes is significant, e.g. CNMESH is meaningful but NCMESH is invalid.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.2 File Names

When OOGL objects are read from disk files, the OOGL library uses the file suffix to guess at the file type.

If the suffix is unrecognized, or if no suffix is available (e.g. for an object being read from a pipe, or embedded in another OOGL object), all known types of objects are tried in turn until one accepts the data as valid.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.3 Vertices

Several objects share a common style of representing vertices with optional per-vertex surface-normal and color. All vertices within an object have the same format, specified by the header key word.

All data for a vertex is grouped together (as opposed to e.g. giving coordinates for all vertices, then colors for all vertices, and so on).

The syntax is

`x y z'

(3-D floating-point vertex coordinates) or

`x y z w'

(4-D floating-point vertex coordinates)

optionally followed by

`nx ny nz'

(normalized 3-D surface-normal if present)

optionally followed by

`r g b a'

(4-component floating-point color if present, each component in range 0..1. The a (alpha) component represents opacity: 0 transparent, 1 opaque.)

optionally followed by

`s t'
`or'
`s t u'

(two or three texture-coordinate values).

Values are separated by white space, and line breaks are immaterial.

Letters in the object's header key word must appear in a specific order; that's the reverse of the order in which the data is given for each vertex. So a `CN4OFF' object's vertices contain first the 4-component space position, then the 3-component normal, finally the 4-component color. You can't change the data order by changing the header key word; an `NCOFF' is just not recognized.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.4 Surface normal directions

Geomview uses normal vectors to determine how an object is shaded. The direction of the normal is significant in this calculation.

When normals are supplied with an object, the direction of the normal is determined by the data given.

When normals are not supplied with the object, Geomview computes normal vectors automatically; in this case normals point toward the side from which the vertices appear in counterclockwise order.

On parametric surfaces (Bezier patches), the normal at point P(u,v) is in the direction dP/du cross dP/dv.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.5 Transformation matrices

Some objects incorporate 4x4 real matrices for homogeneous object transformations. These matrices act by multiplication on the right of vectors. Thus, if p is a 4-element row vector representing homogeneous coordinates of a point in the OOGL object, and A is the 4x4 matrix, then the transformed point is p' = p A. This matrix convention is common in computer graphics; it's the transpose of that often used in mathematics, where points are column vectors multiplied on the right of matrices.

Thus for Euclidean transformations, the translation components appear in the fourth row (last four elements) of A. A's last column (4th, 8th, 12th and 16th elements) are typically 0, 0, 0, and 1 respectively.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.6 Binary format

Many OOGL objects accept binary as well as ASCII file formats. These files begin with the usual ASCII token (e.g. CQUAD) followed by the word BINARY. Binary data begins at the byte following the first newline after BINARY. White space and a single comment may intervene, e.g.

 
OFF BINARY	# binary-format "OFF" data follows 

Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both in big-endian format (i.e., with most significant byte first). This is the native format for 'int's and 'float's on Sun-3's, Sun-4's, and Irises, among others.

Binary data formats resemble the corresponding ASCII formats, with ints and floats in just the places you'd expect. There are some exceptions though, specifically in the QUAD, OFF and COMMENT file formats. Details are given in the individual file format descriptions. See section QUAD: collection of quadrilaterals, See section OFF Files, and See section COMMENT Objects.

Binary OOGL objects may be freely mixed in ASCII object streams:

 
LIST
{ = MESH BINARY
… binary data for mesh here …
}
{ = QUAD
	1 0 0   0 0 1   0 1 0  0 1 0
}

Note that ASCII data resumes immediately following the last byte of binary data.

Naturally, it's impossible to embed comments inside a binary-format OOGL object, though comments may appear in the header before the beginning of binary data.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.7 Embedded objects and external-object references

Some object types (LIST, INST) allow references to other OOGL objects, which may appear literally in the data stream, be loaded from named disk files, or be communicated from elsewhere via named objects. Gcl commands also accept geometry in these forms.

The general syntax is

 
 <oogl-object>  ::=
	[ "{" ]
	    [ "define" symbolname ]
	    [ "appearance" appearance ]
	    [ ["="] object-keyword …
		 | "<" filename
		 | ":" symbolname ]
	[ "}" ]

where "quoted" items are literal strings (which appear without the quotes), [bracketed] items are optional, and | denotes alternatives. Curly braces, when present, must match; the outermost set of curly braces is generally required when the object is in a larger context, e.g. when it is part of a larger object or embedded in a Geomview command stream.

For example, each of the following three lines:

 
	{ define fred   QUAD 1 0 0  0 0 1  0 1 0  1 0 0 }

	{ appearance { +edge } LIST { < "file1" } { : fred } }

	VECT 1 2 0   2 0   0 0 0   1 1 2

is a valid OOGL object. The last example is only valid when it is delimited unambiguously by residing in its own disk file.

The "<" construct causes a disk file to be read. Note that this isn't a general textual "include" mechanism; a complete OOGL object must appear in the referenced file.

Files read using "<" are sought first in the directory of the file which referred to them, if any; failing that, the normal search path (set by Geomview's load-path command) is used. The default search looks first in the current directory, then in the Geomview data directories.

The ":" construct allows references to symbols, created with define. A symbol's initial value is a null object. When a symbol is (re)defined, all references to it are automatically changed; this is a crucial part of the support for interprocess communication. Some future version of the documentation should explain this better…

Again, white space and line breaks are insignificant, and "#" comments may appear anywhere.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.8 Appearances

Geometric objects can have associated "appearance" information, specifying shading, lighting, color, wireframe vs. shaded-surface display, and so on. Appearances are inherited through object hierarchies, e.g. attaching an appearance to a LIST means that the appearance is applied to all the LIST's members.

Some appearance-related properties are relegated to "material" and "lighting" substructures. Take care to note which properties belong to which structure.

Here's an example appearance structure including values for all attributes. Order of attributes is unimportant. As usual, white space is irrelevant. Boolean attributes may be preceded by "+" or "-" to turn them on or off; "+" is assumed if only the attribute name appears. Other attributes expect values.

A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2" or "material { *diffuse 1 1 .25 }", selects "override" status for that attribute.

 
appearance {
  +face               # (Do) draw faces of polygons.  On by default.
  -edge               # (Don't) draw edges of polygons
  +vect               # (Do) draw VECTs.  On by default.
  -transparent        # (Disable) transparency. enabling transparency 
                      # does NOT result in a correct Geomview picture, 
                      # but alpha values are used in RenderMan snapshots.
  -normal             # (Do) draw surface-normal vectors
  normscale 1         # … with length 1.0 in object coordinates

  +evert              # do evert polygon normals where needed so as
                      #   to always face the camera

  -texturing          # (Disable) texture mapping
  -backcull           # (Don't) discard clockwise-oriented faces
  -concave            # (Don't) expect and handle concave polygons
  -shadelines	      # (Don't) shade lines as if they were lighted cylinders
		      # These four are only effective where the graphics system
		      # supports them, namely on GL and Open GL.

  -keepcolor	      # Normally, when N-D positional coloring is enabled as
		      # with geomview's (ND-color ...) command, all
		      # objects' colors are affected.  But, objects with the
		      # "+keepcolor" attribute are immune to N-D coloring.

  shading smooth      # or ``shading constant'' or ``shading flat'' or
                      # or ``shading csmooth''.
                      # smooth = Gouraud shading, flat = faceted,
                      # csmooth = smoothly interpolated but unlighted.

  linewidth 1         # lines, points, and edges are 1 pixel wide.

  patchdice 10 10     # subdivide Bezier patches this finely in u and v

  material {         # Here's a material definition;
                      # it could also be read from a file as in
                      #  ``material < file.mat''

      ka  1.0         # ambient reflection coefficient.
      ambient .3 .5 .3 # ambient color (red, green, blue components)
                      # The ambient contribution to the shading is
                      # the product of ka, the ambient color,
                      # and the color of the ambient light.

      kd  0.8         # diffuse-reflection coefficient.
      diffuse .9 1 .4 # diffuse color.
                        # (In ``shading constant'' mode, the surface
                        # is colored with the diffuse color.)

      ks 1.0          # specular reflection coefficient.
      specular 1 1 1  # specular (highlight) color.
      shininess  25   # specular exponent; larger values give
                      # sharper highlights.

      backdiffuse .7 .5 0 # back-face color for two-sided surfaces
                        # If defined, this field determines the diffuse
                        # color for the back side of a surface.
                        # It's implemented by the software shader, and
                        # by hardware shading on GL systems which support
                        # two-sided lighting, and under Open GL.

      alpha   1.0     # opacity; 0 = transparent (invisible), 1 = opaque.
                      # Ignored when transparency is disabled.

      edgecolor   1 1 0  # line & edge color

      normalcolor 0 0 0  # color for surface-normal vectors
  }

  lighting {         # Lighting model

      ambient  .3 .3 .3  # ambient light

      replacelights   # ``Use only the following lights to
                      # illuminate the objects under this
                      # appearance.''
                      # Without "replacelights", any lights listed
                      # are added to those already in the scene.

                      # Now a collection of sample lights:
      light { 
          color  1 .7 .6      # light color
          position  1 0 .5 0  # light position [distant light]
                              # given in homogeneous coordinates.
                              # With fourth component = 0,
                              # this means a light coming from
                              # direction (1,0,.5).
      }

      light {                        # Another light.
          color 1 1 1
          position  0 0 .5 1  # light at finite position …
          location camera     # specified in camera coordinates.
                              # (Since the camera looks toward -Z,
                              # this example places the light
                              # .5 unit behind the eye.)
          # Possible "location" keywords:
          #  global    light position is in world (well, universe) coordinates
          #             This is the default if no location specified.
          #  camera   position is in the camera's coordinate system
          #  local    position is in the coordinate system where
          #                   the appearance was defined
      }
  }                   # end lighting model
  texture {
        clamp st               # or ``s'' or ``t'' or ``none''
        file lump.tiff         # file supplying texture-map image
        alphafile mask.pgm.Z   # file supplying transparency-mask image
        apply blend            # or ``modulate'' or ``decal''
        transform  1 0 0 0     # surface (s,t,0,1) * tfm -> texture coords
                   0 1 0 0
                   0 0 1 0
                  .5 0 0 1

        background 1 0 0 1     # relevant for ``apply blend''
  }
}                     # end appearance

There are rules for inheritance of appearance attributes when several are imposed at different levels in the hierarchy.

For example, Geomview installs a backstop appearance which provides default values for most parameters; its control panels install other appearances which supply new values for a few attributes; user-supplied geometry may also contain appearances.

The general rule is that the child's appearance (the one closest to the geometric primitives) wins. Further, appearance controls with "override" status (e.g. *+face or material { *diffuse 1 1 0 }) win over those without it.

Geomview's appearance controls use the "override" feature so as to be effective even if user-supplied objects contain their own appearance settings. However, if a user-supplied object contains an appearance field with override status set, that property will be immune to Geomview's controls.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.9 Texture Mapping

Some platforms support texture-mapped objects. (On those which don't, attempts to use texture mapping are silently ignored.) A texture is specified as part of an appearance structure, as in See section Appearances. Briefly, one provides a texture image, which is considered to lie in a square in (s,t) parameter space in the range 0 <= s <= 1, 0 <= t <= 1. Then one provides a geometric primitive, with each vertex tagged with (s,t) texture coordinates. If texturing is enabled, the appropriate portion of the texture image is pasted onto each face of the textured object.

There is (currently) no provision for inheritance of part of a texture structure; if the texture keyword is mentioned in an appearance, it supplants any other texture specification.

The appearance attribute texturing controls whether textures are used; there's no performance penalty for having texture { ... } fields defined when texturing is off.

The available fields are:

 
clamp	none  -or-  s  -or-  t  -or-  st
  Determines the meaning of texture coordinates outside the range 0..1.
  With clamp none, the default, coordinates are interpreted
  modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
  the same point in texture space.  With s or t or
  st, either or both of s- or t-coordinates less than 0 or
  greater than 1 are clamped to 1 or 0, respectively.

file	filename
alphafile	filename
  Specifies image file(s) containing the texture.
  The file file's image specifies color or lightness information;
  the alphafile if present, specifies a transparency ("alpha") mask;
  where the mask is zero, pixels are simply not drawn.
  Several image file formats are available; the file type must be
  indicated by the last few characters of the file name:
    .ppm or .ppm.Z or .ppm.gz  24-bit 3-color image in PPM format
    .pgm or .pgm.Z or .pgm.gz  8-bit grayscale image in PGM format
    .sgi or .sgi.Z or .sgi.gz  8-bit, 24-bit, or 32-bit SGI image
    .tiff 		       8-bit or 24-bit TIFF image
    .gif		       GIF image
  (Though 4-channel TIFF images are possible, and could
  represent both color and transparency information in one image,
  that's not supported in geomview at present.)
  For this feature to work, some programs must be available in
  geomview's search path:
    zcat  for .Z files
    gzip  for .gz files
    tifftopnm for .tiff files
    giftoppm for .gif files

  If an alphafile image is supplied, it must be the same size
  as the file image.


apply	modulate  -or-  blend  -or-  decal
  Indicates how the texture image is applied to the surface.
  Here the "surface color" means the color that surface would have
  in the absence of texture mapping.

  With modulate, the default, the texture color (or lightness,
  if textured by a gray-scale image) is multiplied by the surface color.

  With blend, texture blends between the background color
  and the surface color.  The file parameter must specify a
  gray-scale image.  Where the texture image is 0, the surface color is
  unaffected; where it's 1, the surface is painted in the color given
  by background; and color is interpolated for intermediate values.

  With decal, the file parameter must specify a
  3-color image.  If an alphafile parameter is present,
  its value interpolates between the surface color (where alpha=0)
  and the texture color (where alpha=1).  Lighting does not affect the
  texture color in decal mode; effectively the texture is
  constant-shaded.

background  R G B A
  Specifies a 4-component color, with R, G, B, and A floating-point
  numbers normally in the range 0..1, used when apply blend
  is selected.

transform transformation-matrix
  Expects a list of 16 numbers, or one of the other ways of representing
  a transformation (: handlename or < filename).
  The 4x4 transformation matrix is applied to texture coordinates,
  in the sense of a 4-component row vector (s,t,0,1) multiplied on
  the left of the matrix, to produce new coordinates (s',t')
  which actually index the texture.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Build Daemon user on December, 11 2005 using texi2html 1.76.