The .gfx (short for 'graphics') file format is used to describe/define 3D polygonal models, (both simple and composite), light sources, and scenes. it is an ASCII format that is based on the .OBJ, .GOD, .ALC file formats, with new features for your convenience and for added flexibility. You can use existing .OBJ files to define polygonal models that can be used in the .GFX format to construct larger, more complex models and scenes.

The .gfx file format allows you, at the highest level, do the following:

• OBJECT
  • SIMPLE objects
  • COMPOSITE objects
• LIGHT
• INCLUDE
• SCENE
• a sample .gfx file

• OBJECT definitions - each of which can be one of the two following types:
  
  

  • SIMPLE - this defines a rigid, polyhedral, 3D model using (by default) the .OBJ file format. This allows you to define polygon faces using vertices, texture coordinates (optional), normals (optional), and colors (optional). There is no limit on the complexity of this type of OBJECT as long as it is a rigid model. The syntax is as follows:

    OBJECT name SIMPLE
      FILE filename
    END
    
    
    

    This defines a (SIMPLE) OBJECT with the unique identifier name, and where filename is the name of a .OBJ file where the 3D model data is stored. Please review the .OBJ format specifications for details on .OBJ files. Alternately, you directly specify the content of the .OBJ file inline in the OBJECT definition, as follows:

    OBJECT name SIMPLE
      v  0 0 0
      v  1 0 0
      v  1 0 -1
      v  0 0 -1
      vt 0 0
      vt 1 0
      vt 1 1
      vt 0 1
      vn 0 1 0
      vc 0.4 1.0 0.4 1.0
      f 1/1/1/1 2/2/1/1 3/3/1/1 4/4/1/1
    END
    

    The OBJECT defined in this method should be identical in result as specifying a file name containing the same 3D data.

  ---

  
  

  • COMPOSITE - this defines a composite 3D model using existing OBJECTS (both SIMPLE and COMPOSITE), built-in GLUT/GLU primitives, and modeling transformations. A composite object definition begins the same way as a simple object definition, except the keyword 'SIMPLE' is replaced by 'COMPOSITE'. The following commands are recognized inside a composite object definition:

    • TRANSLATE tx ty tz
      Translate the subsequent subobjects by tx ty tz
      
      
    • ROTATE angle lx ly lz
      Rotate the subsequent subobjects by angle with respect to lx ly lz
      
      
    • SCALE sx sy sz
      Scale the subsequent subobjects by scaling factors sx sy sz
      
      
    • COLOR r g b a
      Specifies the color for subsequent objects. the alpha component a, if not given, defaults to 1.0.
      
      
    • SUBOBJ name
      Draw a previously defined object (simple or composite) called name. This object may be previously defined in the same file or in a file that the current file includes by using the INCLUDE command.
      
      
    • GLU shape parameter(s)
      Draw a GLU primitive. parameter(s) depend on the shape given. the valid shapes are:
      • SPHERE radius slices stacks
      • CYLINDER baseRadius topRadius height slices stacks
      • DISK innerRadius outerRadius slices stacks
      • PARTIALDISK innerRadius outerRadius slices rings startAngle sweetAngle
      
      
      
    • GLUT shape parameter(s)
      Draw a GLUT primitive. paramter(s) depend on the shape given. the valid shapes are:
      • SPHERE radius slices stacks
      • CUBE size
      • TORUS innerRadius outerRadius nsides rings
      • ICOSAHEDRON
      • OCTAHEDRON
      • TETRAHEDRON
      • DODECAHEDRON
      • CONE radius height slices stacks
      • TEAPOT size
      
      
      
    • PUSH
      Saves a copy of current local transformations.
      
      
    • POP
      Restores the matrix saved by the previous PUSH command (and pops the transformation stack). In a composite object definition, there can be more PUSH commands than POP commands (the extra PUSH commands should be implicitly handled at the end of the definition). However, it is illegal to have more POP commands than PUSH commands.
      
      
    • SEPARATOR
      Resets the local transformation to the state of the last PUSH command (without popping it off the transformation stack) or, in the case that the SEPARATOR does not occur between a PUSH and POP, to the state of the local transformation at the beginning of the current object definition.
      
      

• LIGHT definitions (from .ALC format) can specified in one of two ways - either read from a file or define inline in the current file (similar to SIMPLE OBJECT definition). To describe a light source from file (a .LIT file):

  LIGHT name
    FILE filename
  END
  
  
  
  

  To describe a light source inline, simply put the content of the .LIT file in the definition:

  LIGHT name
    AMBIENT r g b a
    DIFFUSE r g b a
    SPECULAR r g b a
    CA ca_val
    LA la_val
    QA qa_val
  END
  
  
  
  

  AMBIENT, DIFFUSE, and SPECULAR specify the color properties of the light. If any are omitted, the values default to (1.0 1.0 1.0 1.0). CA, LA, and QA specifies the constant, linear, and quadratic attenuations of the light respectively. If not specified, CA default to 1.0 and LA, QA each default to 0.0

• INCLUDE command allows you to include the content of another .GFX file. It's syntax is simply this:

  INCLUDE filename
  
  
  This enables COMPOSITE OBJECTs and SCENEs after the INCLUDE statement to use objects defined in filename. Observe the following:
  
  
  • a file cannot include itself.
  • you can only include other .GFX files.
  • circular includes are illegal, and should be caught by the parser.