DirectX 3D File Importer The First and Still-Primary DirectX File Importer Implementation

Please also refer to the corresponding Okino industry-standard DirectX export converter.

Importing Microsoft DirectX X 3D Files

This import converter reads in ASCII and binary DirectX (.x) formatted files. Mesh data (with vertex normals, vertex uv texture coordinates and vertex colors), additional uv sets (via FVFData templates), materials, texture references, hierarchy and object animation are all imported. Either all animation sets can be imported, or just a selective animation set. In addition, vertex weights used for mesh/skeleton deformation skinning are imported and can be played back or re-exported via PolyTrans.

DLL Dependency Note

This DirectX importer depends upon the d3dxof.dll DLL file. This must be placed either in the top-level Okino home directory, in the Windows system32 directory.

If Texture Maps Import & Render Incorrectly

If you find that texture maps do not look correct upon import then simply change the Flip Model to that "Y" Axis is "Up" option.

If Skinned Meshes Import Incorrectly

If a skinned mesh imports incorrectly then simply change the "Method to Convert from LHCS to RHCS" option to another combo box value, such as "Don't do anything". You might also have to toggle the state of the " Flip Model to that 'Y' Axis is 'Up'" option depending on which program you are importing the skinned mesh into.

Lack of An Ambient Lighting Coefficient in DirectX Files

The material definition inside a DirectX file does not contain any information about the ambient shading coefficient. This import converter must assume a specific ambient shading coefficient. What this means is that your imported model may look too washed out if the assumed ambient shading coefficient is too high. This can easily be fixed by modifying the Assumed Ambient Shading Coefficient value below.

Dialog Box Options

Geometry and Material Processing Options

These options control how the imported geometry and material data is processed before it is sent to the NuGraf/PolyTrans internal database.

Create Unique Set of Material Definitions

If this checkbox is check-marked then only a unique set of material definitions will be created based on the imported materials from the DirectX file. If disabled, a material definition will be created for every material specified in the DirectX file.

Remove Double Sided Polygons

While this option is not really needed for DirectX files, it allows double sided polygons to be removed. Double sided polygons are actually 2 physical polygons that occupy the same area in space; each polygon has a reversed orientation. If this option is enabled then one of these double sided polygons are removed. This operation can be very slow to perform.

Hierarchy Optimizer # 1, Hierarchy Optimizer # 2

These options provide methods to remove redundant hierarchy nodes (Frames) from the imported DirectX file. Optimzier # 1 removes runs of empty folders, as well as folders with no children. This optimizer is enabled by default since DirectX files tend to have excess frames in them. Optimizer # 2 is simpler, deleting empty folders which only have 1 geometry object in them. The second optimizer is useful if you batch import a number of DirectX files and find that there are a number of yellow folders (one per imported file) with one a single object in each folder.

Optimize Vertices

If this checkbox is check-marked then redundant vertices will be removed from the imported mesh data.

Optimize uv Texture Coordinates

If this checkbox is check-marked then redundant uv texture coordinates will be removed from the imported mesh data.

Flip Model to that "Y" Axis is "Up"

Okino's PolyTrans and NuGraf software use a "Y" up coordinate system whereas DirectX files might have a "Z" up coordinate system. If you find that the imported model is laying "on it's back" then enable this option.

Flip 'v' Texture Coordinates (Vertically)

If this option is enabled (checkmarked) then all v' texture mapping coordinates will be flipped (inverted) so that the texture maps will appear inverted when rendered using DirectX. It has been reported that DirectX versions 2.0 through 3.0 had a bug in them such that all texture maps were incorrectly inverted. Thus, models that appear correct in v2.0-v3.0 will appear inverted if imported and rendered. To solve this problem, simply enable this option for models imported from DirectX v5.0 or newer if the texture maps appear flipped vertically.

Scale Animation Keys to 3600 Ticks-per-Second Timing

The DirectX file format officially defines its animation keys to be in "tick time", where the default number of ticks per second is 3600 (DirectX8 or older) or 4800 (DirectX9 or newer). Unfortunately, some DirectX programs write out DirectX files incorrectly, outputting their animation keys in 'frames' and not time-based 'ticks'.

If this option is enabled then the DirectX key time values will be re-scaled so that they are converted from the DirectX 3600 ticks-per-second into Okino's more standard and common 4800 ticks-per-second. If the DirectX file defines a "ticks per second" template ("AnimTicksPerSecond") then that value will be used instead of the default 3600 value (such as 4800).

If this option is disabled then no animation time scaling will be performed. Most often you will want to disable this option if you perceive the animation is playing back too fast (3600 times too fast!). In such cases, the original DirectX file was written incorrectly as "frames per second" and not the 'ticks per second' as it should have been.

Assumed Ambient Shading Coefficient

A limiting factor of the DirectX file format is the lack of an ambient shading coefficient in the material definition. Thus, if you export out a generic model to a DirectX file, and import it into PolyTrams, the ambient shading value of the imported material will probably not be the same as the original ambient shading value. This type-in box allows you to specify the ambient shading coefficient for all materials imported from the DirectX file. The default value is 0.3, and the valid range is 0.0 (no ambient) to 1.0 (100% ambient contribution). If the imported model appears to be too washed out then set this value lower.

Shading Coefficient Modifcations

See below for a longer explanation of these combo boxes. In general, these combo boxes allow the key material attributes to be tweaked during import. This might be necessary, for example, if the imported objects appear too ambient, or too luminous.

Method to Convert from LHCS to RHCS

DirectX, by its very definition, uses a left handed coordinate system. However, all Okino software (and many 3D software packages) use a right handed coordinate system. This drop-down combo box specifies how the DirectX importer should try to convert the imported model from left handed coordinates to right handed coordinates:

Dont Do Anything

Nothing is done to the imported model.

Flip Z of Vectors and Reverse Angle of Quaternions

The Z component of each vector is negated, and the angle of all quaternion rotations is negated.

Flip Z of Top-Level Matrix

If the DirectX file was originally exported using the Okino DirectX exporter, then that exporter overcomes the RHCS to LHCS problem by setting the Z component of the top-level Frame matrix to -1 (essentially mirroring the world in the XY plane). To un-do this change, select this combo box option and the DirectX importer will simply negate the Z component of the top-level transformation matrix imported from the DirectX file.

Enable Import of Skin Weights (Mesh Deformations)

"Mesh skinning" is the process of deforming a single skin mesh with a skeleton (in the .X file the skeleton is represented by the frame matrices which define the pivot point and orientation of each invisible bone). The contribution of each bone of the skeleton to the deformation of a vertex in the mesh is controlled by vertex weights. If this option is enabled then a mesh will be bound to one of more "frames" in the .X file (which represent the bones or joints of the skeleton) via transformation matrices and weight values.

If the importer detects the use of DirectX "Frame" matrices as bones for mesh deformation, it will go over the hierarchy and re-tag them as "Joint/Bone" nodes so that they appear visually as bones within Okino's stand-alone PolyTrans/NuGraf software.

Renormalize All Vertex Bone Weights

By convention, the summation of all the bone weights associated with each vertex of a mesh should add up to 1.0. However, there are cases where this is not true with imported .X files, often due to badly written programs where the .X file was originally exported. Enabling this option (which is the default) will re-normalize the bone weights so that they add up to 1.0.

Reparent Skinned Meshes to "World" Level

This option solves problems when importing skinned meshes which have animation and/or hierarchical transformations on them (such as when a skinned mesh is imported via .X from Character Studio in 3DS MAX).

To have "skinning" in a DirectX two things are needed: a mesh and a hierarchy of "Frame" nodes which represent a skeleton of bones. Normally the mesh is NOT located within the hierarchy of the skeleton. However, programs such as Character Studio (3DS MAX) will allow a mesh to be parented somewhere within the skeleton hierarchy, and allow for the mesh to be animated and also to inherit transformations from its parent skeleton nodes.

Most programs which support mesh skinning completely ignore all animation and transformations which are applied and associated with a mesh object that is being skinned. However, Character Studio allows this. If you import such a file into Okino's stand-alone PolyTrans or NuGraf packages, and the "Ignore animation on skinned meshes" option is not turned on, then the skinned mesh will look incorrect due to this extra level of transformations being applied.

A generic solution is to enable this "Reparent Skinned Meshes to World Level" option. It will simply move the skinned mesh out of the skeleton hierarchy and re-parent it at the "world-space" level of the hierarchy. By doing so the skinned mesh will no longer be affected by any inherited animation or transformation data.

The "Set Skinned Mesh Transform To Identity" checkbox should also be enabled at all times so that the current transformation matrix of the skinned mesh object gets reset to the Identity matrix. This is necessary since the transformation of the skinned mesh should only be affected by the associated skeleton and not any local transform of the mesh itself.

Selective Loading

These options allow specific portions of the DirectX file to be imported.

Vertex Normals

If checkmarked, vertex normals will be imported for each object. DirectX files contain vertex normals which are used to make the imported object appear smooth when shaded.

Vertex Colors

If checkmarked, vertex colors will be imported for each object. However, not all export file formats can handle vertex colors. This option is disabled by default because the objects normally receive their color from the material definitions.

Vertex Texture Coordinates

If checkmarked, vertex uv texture coordinates will be imported for each object. These texture coordinates (if provided) are necessary in order for 2d bitmap textures to be applied to objects.

Additional Texture Coordinate Uvsets (FVF Data)

The DirectX file format does not explicitly allow for multiple sets of uv texture coordinates to be specified - a single set of uv coordinates for a mesh are specified via the default MeshTextureCoords template. However, with the introduction of DirectX v8.1, a "back door" method was provided to allow up to 7 additional sets of uv values to be specified for each mesh vertex via the "Flexible Vertex Format" data array ("FVFData" template).

If this checkbox is enabled then the importer will load the "FVF Data" array and attempt to pick out up to 7 additional uvsets per mesh. The file must have the additional uvsets specified in the "FVFData" template (programs such as Okino's DirectX exporter and the Unwrap-3D program can output this template data). Also, the uv-set data must be defined as pairs of 2D (u,v) float values -- 1D, 3D and 4D texture coordinates are not explicitly parsed or supported.

The uv set imported from the MeshTextureCoords template will go into "uvset0" and the additional uvsets from the FVFData template will go into uvset1, uvset2, etc. If no data is found for the MeshTextureCoords template then any uvsets loaded from the FVFData template will go into uvset0, then uvset1, etc.

Object Hierarchy

If checkmarked, the object hierarchy will be recreated from the Frame hierarchy inside the DirectX file (if such hierarchy exists). In most cases you will need to keep this option enabled if you wish to import object animation data.

Animation Sets

If checkmarked, object animation data will be imported from the DirectX file and one or more of its "AnimationSets". For this option to work properly you must enable 'Object Hierarchy' import as well.

The DirectX file format allows for multiple animation sets to be defined. In 3D game design it is often useful to have a series of reuseable animation 'clips' for common character cycles, such as an animation clip for walking, jumping, running, etc. In DirectX these are called 'animation sets'. The combo box beside the checkbox determines which animation set is to be imported. If set to "All animation sets" then all animation sets will be imported, composited together onto a single animation timeline. Otherwise, you can choose the first through 255th animation set to import.

Vertex Duplication List

DirectX8 introduced a new template called a vertex duplication list. It specifies which vertices in a mesh had to be duplicated during its export process due to different adjacent materials at a polygon boundary. By using this list during import the redundant vertices can be unlinked from the mesh and no longer referenced.

Statistics and Warning Messages

Report Statistics About the Geometry File

If this checkbox is check-marked then parsing statistics will be displayed in the message window after the DirectX file has been imported.

Print Warning Messages

If this checkbox is check-marked then warning messages from the DirectX file parser will be printed out to the message window.

Shading Parameter Modification Combo Boxes

These combo boxes provide hands-on control over how imported material shading parameters should be modified so that the imported model can be rendered nicely in a photo-realistic rendering program. All too often the imported model appears "too ambient" or "too diffuse" resulting in rendered images that are washed out or with no gradual shading effects visible. The two combo boxes and the single numeric type-in box provide you good control over the ambient, diffuse, specular, luminous and reflection shading coefficients imported into PolyTrans/NuGraf, as well as the opacity of the material, its index of refraction (IOR) and Phong shininess value.

The first drop-down combo box selects which of these shading parameters you want to modify. Each shading coefficient has its own operation which can be selected (the second combo box) and an optional numeric type-in value (the third data entry text input). The following describes the various shading parameters that can be controlled:

• Diffuse Coefficient: This controls the amount of color reflected from an object based on the direct light shining on it. A good default value is 0.4 and ideally ranges from 0.0 to 1.0. Some programs have a diffuse shading coefficient parameter (NuGraf/PolyTrans, Electric Image, etc) while others do not (3D Studio). If an export file format does not support a diffuse shading coefficient then this value will be multiplied into the diffuse shading color itself.
  
  
• Specular Coefficient: This controls the intensity of the highlight color on an object. A good default value is 0.7 and ideally ranges from 0.0 to 5.0. If an export file format does not support a specular shading coefficient then this value will be multiplied into the specular shading color itself.
  
  
• Luminous Coefficient: This controls how much color is added directly to an object, irrespective of any light which shines on it (the higher the value, the more the object will appear to glow). In general you should keep this value at 0. If an export file format does not support a luminous shading coefficient then this value will be multiplied into the luminous shading color itself.
  
  
• Opacity: This is the inverse of transparency. 0.0 will make the object fully transparent, while at 1.0 the object will be fully opaque.
  
  
• Phong Shininess: This controls the width of the specular highlight seen on an object. An ideal range is 6 (very wide) to 300 (very narrow). The default is 32.

For each material shading parameter, several actions can be performed on it during the import process:

• Do Not Import: The shading parameter is not imported at all. No value is imported nor sent to PolyTrans/NuGraf. Thus, the default material shading parameter value (as set inside PolyTrans/NuGraf) will be used instead.
  
  
• Import Unchanged: The shading parameter is imported as is, with no change.
  
  
• Set and Use Default: The shading parameter is set to some good default value (as determined by the import converter). This default value will be shown in the type-in box.
  
  
• Set to Specific Value: The imported shading parameter will be overridden with the user specified value of the numeric type-in box.
  
  
• Import and Crop by: The shading parameter is imported and will remain unchanged if it is less than the numeric type-in value shown on the dialog box. If it is greater, then the imported value will be clamped to be no greater than the numeric type-in value. This is a good operation, for example, if you do not wish for the ambient shading coefficient to be greater than 0.3.
  
  
• Import and Scale by: The shading parameter is imported and multiplied by the numeric type-in value shown on the dialog box
  
  
• Normalize Color and Coefficient: This option only applies for the ambient, diffuse, specular and luminous shading coefficients and their respective RGB colors. This option is a hybrid approach which tries to automatically guess at a proper shading coefficient value given the raw (and corresponding) color imported from the file. As mentioned, the shading coefficient is needed to create nice looking (nicely shaded) images in a photo-realistic rendering program. If this option is chosen, then the specific shading coefficient will be derived directly from the relative intensity of the imported color which corresponds to this shading coefficient (diffuse color for diffuse shading coefficient etc.). For example, if the imported diffuse color is (0.4, 0, 0), which is 40% of full-bright red, then the diffuse shading coefficient will be set to 0.4 and the diffuse color will be modified to be (1, 0, 0). When the new color (1,0,0) and the new shading coefficient (0.4) are multiplied together, it results in the original color imported from the file (0.4, 0, 0). In general you may wish to use the Set and Use Default option to get good rendered results.