GameExchange-2 Exporter

Exporting Game Exchange 2 Files

The GameExchange2 geometry export converter writes out a hierarchy of ASCII .gof, .grp., .gbf, .gmf, .gcf, .gaf and .glf files which represent a "GameExchange" scene tree.

GameExchange2 is a verbose file format that can potentially convey any sort of 3D scene data and related information. It is based on the concept of "templates" which dynamically define the syntax and contents of the files. This exporter saves its own copy of templates to the exported directory so that any 2.1 or newer GameExchange reader can understand the data files written.

Main	Auto-Convert	Bitmap Paths	Materials	Animation

Quick Start Notes

If you output animation then load up the file with the ".gaf" extension in the destination program. All animation is stored in the .gaf file and this should be the one to be loaded when animation is required.

If no animation is enabled or output then you will want to load up the .grp group file. This is the single file which groups together all object .gof instance files.

About 'Game Exchange'

Game Exchange provides a mechanism for converting object, material, and animation data into a set of intermediate ASCII file formats. These ASCII files can then be read by GameExchange compliant import converters such as the Mirai and N.World products from IZware. The development and maintenance of the GameExchange API and related libraries is handled by IZware.

Game Exchange data is saved to disk as several distinct files that form a set:

• GRP (the main file to import; contains the scene file list)
• GOF (instances of raw object definitions)
• GBF (raw object 'body' definitions from which instances can be easily created)
• GMF (material definitions)
• GAF (animation)
• GSF (skeleton - not used during import)
• GLF (lights)
• GCF (camera)
• GEF (environment)

Each of these file types describes a different aspect of the scene exported from N•World or Mirai. In addition to the standard set of N•World and Mirai parameters exported with each file type, the user can also define custom parameters for the scene. This allows the user to quickly add parameters that are supported by the target game engine.

• GRP Files - GRP files contain references to the files that must be parsed together. Since all of the files for a scene will be parsed together, a GRP file lists all of the files for a scene. If the scene is animated, all of the animation data is kept in a GAF file, which references the GRP file.
  
  
• GOF Files - GOF files describe a single object. This object may be a terminal object or a hierarchical object with several subobjects. More recent versions of GameExchange place the raw geometry data in the GBF (body) file and the reference/instance to the geometry data in the GOF file (the matrix and material assignments).
  
  
• GAF Files - GAF files describe from one to three elements:
  1. Animated light objects
  2. Animated camera object
  3. A single object

  The location of the object and animated lights and camera are described frame-by-frame. If an object is composed of subobjects, the location of the object is described first and is followed by the location of the subobjects. The GAF file references the GRP file (described above) for the scene, but is referenced by no other files.
  
  

• GMF Files - Materials associated with an object are described in a GMF file, which contains descriptions for one or more materials. A GOF file may reference only a single GMF file, but a GMF file may be referenced by many GOF files.
  
  
• GSF Files - GSF files describe single or multiple skeletons including:
  1. Skeleton hierarchy including the skeleton name, bones, and joints
  2. Descriptions of all base states
  3. Descriptions of each pose
  4. Listing of all hard and soft parts associated with each bone

  Any skins associated with the skeleton are exported as gobjects, which are exported Mirai objects. They are described in GOF files. This exporter does not handle skeleton data or output GSF files.
  
  

• GLF Files - GLF files contain information about all the lights in a scene exported from Mirai.
  
  
• GCF Files - A GCF file contains information about the camera. If the camera was animated, the GCF file contains the initial position of the camera; frame by frame animation data is included in the GAF file.

Entities Exported via the GameExchange2 Exporter:

• N-sided polygonal mesh data to .gbf files. Vertex normals, uv texture coordinates and vertex colors can all optionally be output.
  
  
• Full hierarchy information for objects with the use of .gof files for instancing of existing geometry (body) data.
  
  
• Output of the "Render domain" material definition with ambient, diffuse, specular and emissive color. Color opacity (ganged with highlight opacity), the phong shading model (and associated specular exponent) are also output.
  
  
• For texture mapping, the diffuse, opacity and bump maps are output. More could be output (such as specular color map, luminous color map, highlight color map) but these types of texture maps are not defined by GameExchange v2.1. With each texture map is output the (u,v) scale and offset values (appropriately modified for the inverted uv coordinate system fo GameExchange), the bump mapping factor and the wrap around flags (STD for both wrap-arounds enabled, or CLAMP for both wrap-arounds disabled or if either wrap-around flag is disabled).
  
  
• For each texture map reference added to the .gmf material file, the actual texture map image itself can be automatically cross converted to any 2d bitmap image file format supported by PolyTrans.
  
  
• Perspective cameras with the look-from, look-at, look-up, field-of-view and the near/far clipping planes.
  
  
• Ambient light with intensity and color. Point light with intensity, color and location. Directional lights with intensity, color and direction. Spot lights with intensity, color, shine-from, shine-at, attenuation, spot-angle and fall-off angle.
  
  
• Scale, rotation and translation 'keyframe' animation data for objects. Location, orientation and field-of-view animation for cameras. Note this is the explicit 'keyframe' type of animation data and not the 'offset' form of animation data supported by Mirai. Since Mirai and GameExchange2 do not have the concept of pivot points and locally defined animation transforms, all animation is output in world-space coordinates (in such cases all hierarchy nodes above the leaf node are identity transforms).

Current Exporter Limitations

1. GameExchange only allows materials to be assigned to bodies in the .gbf files (the raw geometry data object) and not to the instances of the objects. However, Okino software allows geometry bodies to be instanced multiple times and each instance is allowed to have its own material definition. Thus, if you output 4 instances of a sphere with different materials assigned, only the first material will show up inside the destination program. We hope that the GameExchange file format will be amended someday to allow material overrides at the instance level.
   
   
2. The concept of image cropping in Mirai is not the same as the concept of image cropping in NuGraf/PolyTrans. In Mirai cropping an image only makes less of that image visible on the textured surface; the scaling or appearance of the image does not change, only the amount of the texture is cropped. In NuGraf/PolyTrans, cropping an image sets the portion of the image which will be used in the texture mapping process; if have have a polygon texture mapped, a cropped image will make the cropped area of the image appear across the entire polygon face - the area of the polygon textured will remain the same, only the sub-set of the image which maps to this region will change.
   
   
3. Many 3D file formats allow the texture map wrap-around flag to be enabled in the U, V or UV directions. However, GameExchange ("MAP-BOUNDARY") only allows them to be enabled in the UV directions at the same time (STD), or disabled completely (CLAMP). Thus, for the wrap-arounds to be enabled (STD) in GameExchange this exporter requires that both U and V wrap-arounds from the PolyTrans database both be enabled.

Main Dialog Box Options:

Copy GameExchange Templates to Destination Directory

As mentioned above, the syntax for the GameExchange file format is dynamic, being defined at runtime by the contents of "template definition" files. This exporter writes to the GameExchange 2.1 file format. To make the export process complete it must also write out the template files which define the syntax adhered to by this exporter. The dialog box option "Copy GX Templates to Destination Directory" (enabled by default) will copy the GX 2.1 templates from specified source directory to the destination export directory. The files copied are: gaf-2-1-0-0.tpl, gbf-2-1-0-0.tpl, gcf-2-1-0-0.tpl, gef-2-1-0-0.tpl, glf-2-1-0-0.tpl, gmf-2-1-0-0.tpl, gof-2-1-0-0.tpl and gsf-2-1-0-0.tpl. The source directory defaults to the Okino "vcplugin" directory; you can select an alternative source directory by pressing the Browse button. Any files which have the extension .tpl will be copied from the source directory to the destination directory.

Output Mesh Data

If this checkbox is enabled (checkmarked, which is the default) then the raw mesh data will be output to the .gbf body files.

Normals

If this checkbox is enabled (checkmarked, which is the default) then vertex normals will be output to the .gbf body file. Vertex normals define how smooth or how faceted/angular the mesh data will appear.

Texture (u,v) Coordinates

If this checkbox is enabled (checkmarked, which is the default) then (u,v) texture coordinates will be output to the .gbf body file. (u,v) texture coordinates are needed for texture mapping. They define which part of a flat texture map will get applied to which part of the 3D mesh object.

Vertex Colors

If this checkbox is enabled then vertex colors will be output to the .gbf body file. This option is disabled by default it is not very common to have vertex colors transfer between 3D file formats, but rather color of polygons often comes from material definitions.

Reverse Orientation of all Polygons

If this option is enabled (checkmarked) then the orientation of all polygons will be reversed (this will effectively swap the orientation of the polygons’ geometric normals).

Triangulate Concave Polygons

If this checkbox is check-marked then all concave polygons will be triangulated before being output to the .gbf body files. This option is disabled by default which will allow concave polygons to be output to the .gbf body files.

Triangulate All Polygons

If this checkbox is check-marked then all polygons will be triangulated before being output to the .gbf body files. This option is disabled by default. Please note that this option overrides the previous ‘Triangulate Concave Polygons’ option if it is enabled.

Ouput Materials

If this checkbox is enabled (checkmarked, which is the default) then materials will be output to the .gmf material file. See above for the description of which material attributes are output.

Output Texture Bitmap References

If this checkbox is enabled (checkmarked, which is the default) then references to bitmap textures will be output along with the material definitions in the .gmf file. Diffuse, opacity and bump map texture references can be output along with u/v scale and offset values, CLAMP/STD wrap-around flags, and the bump map factor.

Output Cameras

If this checkbox is enabled (checkmarked, which is the default) then all defined perspective cameras will be output to the .gcf file with the look-from, look-at, look-up, field-of-view and the near/far clipping planes.

Output Lights

If this checkbox is enabled (checkmarked, which is the default) then lights will be output to the .glf file. Ambient light with intensity and color. Point light with intensity, color and location. Directional lights with intensity, color and direction. Spot lights with intensity, color, shine-from, shine-at, attenuation, spot-angle and fall-off angle.

Auto-Convert-Bitmaps Dialog Box Options:

This dialog box allows referenced bitmaps (of the internal 3D scene database) to be automatically converted to other 2d bitmap formats during the export process.

The three options available are:

• Do not modify the bitmap filename reference and do not perform any bitmap conversion.
  
  
• Modify the extension of the bitmap filename to a bitmap format (chosen from a drop-down list) but do not perform any bitmap conversion. This option is useful if you have (1) either performed the bitmap conversions in a previous export process or (2) you wish to use an external program (such as PhotoShop) to perform the bitmap conversions.
  
  
• Perform bitmap conversion and change the file extension of the bitmap. For example, if your original 3D scene data referenced JPEG bitmaps, but you want the exported GameExchange .gmf file to reference BMP bitmaps, then this option can be used to automatically convert the JPEG files to BMP and change all bitmap references to the new BMP files.

No Bitmap Conversion or Bitmap Filename Changes (Radio Button)

If this radio button is chosen then any bitmap reference exported into the GameExchange .gmf file will not be changed, its filename extension won't be changed, the path to the bitmap will not be changed and no bitmap conversion will be done.

Convert all Bitmap File References To... (Radio Button)

Rather than convert referenced bitmap images to another file format this radio button (when selected) simply changes all the file extensions on bitmap files to a specific type. For example, if set to "TIFF" then all bitmap filenames exported to the GameExchange .gmf file will be changed so that their file extensions end in ".tif". This is a useful option is you already have all of the referenced texture maps converted to the desired file format (either from a previous invocation of this export converter or by using a batch bitmap conversion program).

Auto-Convert Bitmap Files to Another Format (Radio Button)

If this radio button is selected then all 2d bitmap textures which are currently defined and referenced by the internal NuGraf/PolyTrans database scene will be automatically tagged then converted to a new user-specified 2d bitmap file format during export. The desired format is chosen using the Bitmap File Format combo box. If the texture(s) cannot be found in the location specified by the pathname prepended to the input texture filename then the export converter will search for the texture(s) in all directories specified in the 'Default Search Path' and the 'Texture Bitmaps Search Path' file search paths (these can be modified by choosing the 'Preferences/Configure File Search Paths' menu item.

Bitmap File Format (Combo Box)

This combo box lists the destination bitmap file format.

Bitmap Depth (Bits/Pixel): 2, 4, 8, 24

These radio buttons determine the number of bits/pixel to write out to the new 2d bitmap file. The default is 24 bits. A color quantization algorithm will be used for the 2, 4 and 8 bits/pixel output formats.

Dimensions: X = #, Y = #

These two drop-down list boxes determine the X and Y resolution for the converted bitmap file(s):

No Change	= Do not change the X or Y size
Closest	= Use the next highest power-of-2 size
2, 4, 8, ... 256, 512	= Choose a specific size for the X or Y dimension

Confirm Potential Bitmap File Overwrites

If this checkbox is enabled (checkmarked) then the bitmap converter will confirm any potential overwrites of existing bitmap files on disk which have the same filename and extension as the one being written. If this option is disabled then no confirmation will be made.

Save Converted Bitmaps To...

These radio buttons determine where the new bitmap file will be written to. Note that enabling the 'Replace all Bitmap File Paths With This Path:' option or the 'Strip File Paths From All Bitmap References' option below will change the path prefix for the converted bitmap even though it was saved to disk in the location specified by one of these 2 radio buttons.

Directory Where Geometry Is Being Exported

The new bitmaps will be written to the directory where the GameExchange .gmf file is being exported to.

Specific + Browse

The new bitmaps will be written to the directory specified by the text box. This directory can be changed by press the 'Browse' button.

"Bitmap Paths" Dialog Box Options:

Convert all file paths to UNIX format

If this option is enabled (checkmarked) then all bitmap file paths written to the GameExchange .gmf file will be converted to a UNIX compatible format. In particular, all DOS-specific backward slashes '\' will be converted to UNIX forward slash '/' directory separators. Also, any DOS-like drive specifiers, such as "c:\" will be removed from the file path and a warning message will be reported about the removal of this drive specifier (you should make sure that all DOS-like drive specifiers be replaced by UNC specifiers, such as \\machine1\). If this option is disabled then no conversions will be made.

Strip File Paths From All Bitmap References

If this checkbox is check-marked then all bitmap file references will have their filename path removed from them prior to export to the GameExchange .gmf file. If this option is disabled then the filepath and filename to the bitmap reference will not be changed.

Use Absolute Paths for all bitmap file references

If this checkbox is check-marked then all bitmap files which are stored as references in the GameExchange .gmf file will have an absolute filepath prefixed to them. This option should only be enabled if the location of the bitmap files is not to change after the conversion process is done. If this option is disabled then the bitmap references will be output with no changes at all; such references may or may not have absolute file paths on them.

Replace all Bitmap File Paths With This Relative Path

This option allows all bitmap references exported to the GameExchange .gmf file to be prefixed with a new relative filepath. This might be useful, for example, if all of your bitmap files are located in one specific directory or if you wish to change the prefix on the imported bitmap references. This new path will override all other options on this bitmap conversion dialog box (in other words, it will replace a bitmap's file path regardless of any other file path added to the bitmap via other options in this dialog box). To choose the filepath press the "Browse" button. To disable this option, click on the checkbox again so that it comes un-checkmarked.

Materials Dialog Box Options:

This dialog box contains options that control how the internal material definitions are modified before they are output to the GameExchange materials (.gmf files). In general you will never have to modify these values; they are provided for expert use.

Shading Coefficient Overrides

In many 3D rendering software packages there are parameters called "shading coefficients". These provide a sort of "balancing" or mixing between the overall ambient, diffuse, specular and luminous color values used to compute the final shaded color of an object. However, GameExchange does not have such shading coefficients and only has raw ambient, diffuse, specular and luminous RGB colors. To overcome this limitation four slider have been provided on this panel. If enabled, the shading coefficients shown on this panel will be multiplied into their corresponding RGB colors prior to export to the .gmf files. For example, if you find that the ambient color is too strong in the destination program then enable the checkbox to the right of "Ambient" and optionally modify the slider; moving the slider to the left will make the ambient color darker and less strong, while moving it all the way to the right will output the ambient color unmodified.

If the checkbox is unchecked (disabled) then the default PolyTrans/NuGraf internal shading coefficients will be multiplied into their corresponding RGB colors instead.

Shading Coefficient Multipliers

These values are explicit multipliers for the ambient, diffuse, specular and luminous RGB colors exported to the GameExchange .gmf file. These form a similar role to the sliders shown in the "Shading Coefficient Overrides" section except that (1) they are used regardless of whether those checkboxes in the previous section are enabled or not, (2) the weighing factor can be used to scale the color darker (value less than 1.0) or bright (value greater than 1.0).

For example, if you are finding that the diffuse output to the GameExchange files are not bright enough then you could change the ‘Diffuse' multiplier to 1.5 which will cause all diffuse colors to be increased by 1.5 times in brightness.

Other Shading Multipliers

Likewise, these values are multipliers for the GameExchange diffuse color and the specular exponent glossiness. The diffuse color multiplier is equivalent to the diffuse shading coefficient multiplier. For example, if the ‘Diffuse Color’ multiplier is set to 1.5 then all diffuse colors will become 1.5 times brighter while if set to 0.5 then all diffuse colors will become 50% darker.

Animation Dialog Box Options:

The following options control the hierarchy and animation output options of this GameExchange exporter. Unlike other Okino exporter which output keyframe animation data relative to local pivot points, this GameExchange exporter outputs explicit 4x4 transformation matrices at each frame for objects (in world-space) or location/aim/look-up/field-of-view values for cameras (in world-space).

Output Object Hierarchy Information

If this checkbox is enabled (checkmarked, which is the default) then hierarchy information will be output to GameExchange via .gof files. Hierarchy must be enabled if object animation is to be output.

Output Object Animation

If this checkbox is enabled (checkmarked, which is not the default) then object animation data will be output to the GameExchange .gaf file. Since GameExchange does not have any concept of pivot points, all object animation data will be output in world-space coordinates. The scale, rotation and translation of the object animation can be output.

Output Camera Animation Data

If this checkbox is enabled (checkmarked, which is not the default) then camera animation data will be output to the GameExchange .gaf file. The location of the camera will be output in world-space coordinates. The location, orientation and field-of-view for the camera will be output at each frame.

Output Every Nth Animation Frame

By default this exporter outputs animation data by sampling the location of objects or cameras at every frame and outputting transformation data on a frame by frame basis. If you would rather output the data every second frame, then set this type-in value to 3. If every third frame, then set to 3. Etc.

Frame Rate

Internally, all animation data is stored in terms of time. However, GameExchange animation data is output in terms of frames. To convert from time to frames, this frame rate parameter is used. Common frame rates are 24fps (film), 25fps (PAL) and 30fps (NTSC video). If your animation is 1 second long, and 30fps is selected, then 30 GameExchange frames will be output.