Click here to read Okino's GameExchange press release.
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.
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)
GSF (skeleton - not used during import)
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:
Animated light objects
Animated camera object
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:
Skeleton hierarchy including the skeleton name, bones, and joints
Descriptions of all base states
Descriptions of each pose
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
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.
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.
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.
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.
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.
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.
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.
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
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
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
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
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
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.
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.