[ HOME ][ API ][ MEL ]

 

- The Maya Exporter Factfile -

(C) Robert Bateman - 20/June/2004

Last Updated - 9/September/2004

Thanks to the following people who have notified me
of a number of corrections and improvements :

Adam Cubitt
Florain Loitsch

Richard Morton
James Whitworth
Katrin Schmid

 

 

The information provided here is designed to take you beyond the exporter basics and allow you to impliment a fully working, functional and stable maya exporter written in the MayaAPI.

For the sake of simplicity, all error checking has been removed from the source examples provided. I generally recommend always checking for errors because you never know what un-expected things an animator might do with a character. Therefore always be on the lookout for un-expected situations.

A number of framework examples exist to provide you with a few possible starting points. There are also a few source examples at the bottom of this page of varying degrees of complexity.

 

 

Exporter FrameWork Source
(VC .Net & linux makefile)
 

 

A number of different ways exist which we can use to impliment an exporter. How you impliment your exporter largely comes down to how it will fit into your graphics pipeline.

If you want to export files from within maya, then the FileTranslator plugin is the place to start. This will allow you to export from maya using File->Export as you would any other file.

If you are intending to use an automated graphics build process then you might want to consider a writing a command line application using MLibrary.

You might also consider the possibility of writing a mel script to automate your export process. This can be executed using the "-batch" flag when running maya to process a number of files. In this case, a plugin mel command may well be useful.

 

 
   
Some Maya API Basics
 

 

These are simple introductory sections into the maya API and navigating the scene data. If you are new to Maya, I would strongly suggest getting an animator to give you a quick tour of some maya basics before delving into the API. In particular knowledge of the Channel box, Attribute Editor and the hypergraph are essential to be able to happily work with Maya.

Often people come to the Maya API having some prior knowledge of mel. Unfortunately, this knowledge will not help you to understand how the API works as much as you would have thought. The Maya API is ultimately 100% Object Orientated, mel script is 100% structured. It is however used to create user interfaces which tie your custom nodes and mel procedures into the fabric of Maya.

The API is much easier to understand if you have some basic knowledge of the way that Maya works from the user point of view. Spend as much time as is needed getting to know the Hypergraph and how to navigate it. It gives you an exact graphical representation of how the nodes are represented in the API, and is therefore invaluable!

If you are adding support for a new feature into your exporter then I would suggest sitting down with an animator to see how they actually use that feature within Maya. One such example would be adding support for IK chains. As a programmer, you may start by researching a bit on the internet to see what data you need. The results might show that you only need to consider the IK handle, the IK effector, and the joints in-between when exporting the data. In reality however your animator may actually be relying upon various constraints, driven keys, expressions etc to actually control the IK chains animation.

To make the life easier for both the tools programmer and the art department, you should really sit down and build a list of minimum requirements. As a programmer, your minimum requirements are probably going to be very different from those of an animator. From personal experiance, I can say that if an animator disagrees with a decision from a programmer where the toolset is concerned, you should simply reject the idea. A programmer may well save a day by implementing the feature their way, but you may well find that your 50 strong art department each end up wasting an hour a week.

 

 
   
Surface Properties
 

 

These topics cover all the fun aspects of getting materials and texture data from maya.

 

 

 

 

 

 

Textures

Materials

Bump Maps

Environment Maps

 

   
Shapes
 

 

These Node types are essentially those parented under transform nodes. It may at first seem logical to want a camera position or a light, however a more generic solution is to simply refer to the parent transform for positional information.

This means that nodes such as meshes and nurbs surfaces are output in local space.

 

 

 

 

 

 

Polygonal Meshes

Nurbs Surfaces

Nurbs Curves

Lights

Cameras

Locator Nodes

 

   
Transforms and Animation
 

 

Within maya, the MFn::kTransform forms the base class of all transform nodes. Transforms are ordered into a scene hierarchy that essentially describes the spatial position of the shape nodes within the scene.

Maya stores animation data as hermite animation curves which are attached to individual keyable attributes. Although at first it may seem a good idea to read the animation curves directly, bear in mind that if the character was animated using Ik chains, constraints or expressions, then you will have to also export this information and re-create it within your viewing code.

Often the most reliable (and simple) method of exporting animation data is to sample each transform over a specified time range. In this case you could either sample the rotation data in euler angles, quaternions or matrices. Scale and Transformation values might also be considered for export.

It should be noted that all example code here only access quaternions. Consult the MFnTransform or MFnIkJoint documentation for information on how to access the rotation data in Euler angles or matrix form.

 

 

 

 

 

 

 

Transforms

Sampled Animation Data

Animation Curves

IK Chains

Constraints

 

   
Deformers
 

 

Deformer Nodes act upon surfaces within your scene. I use the term 'surfaces' however in real terms this usually means one of the following node types :

  • MFn::kMesh
  • MFn::kNurbsSurface
  • MFn::kNurbsCurve
  • MFn::kLattice
  • MFn::kSubDiv

essentially a deformer just moves the control points or vertices of the shape. If you are only using skinning on mesh surfaces, then you can also assume that the normals are also influenced by the deformer. Unfortunately the more deformation types you add support for in your own engine increases the complexity of deforming the normals.

 

For a truly generic solution then, it is probably better to calculate surface normals, bi-normal and tangent vectors for meshes on the fly. This would allow you to simply impliment a generic Geometry base class, which contains a list of points, on which a deformer acts. A virtual draw function can then specialise the rendering of that surface type. I would recommend looking at the nvidia mesh-mender library that calculates normals and tangents for you if you were to go down that route.

 

 

 

 

 

   
Dynamics
 

 

Maya contains some fairly extensive dynamics and particle engines. However, due to the flexibility that Maya affords when dealing with this, you may want to either use a limited sub-set of features, or use custom plugin nodes for particle systems and fields which better represent those you will use in your game engine.

 

 

 

 

 

   
Utilities
 

 

This section of the factfile details some utility classes within the Maya API, as well as presenting information though not directly related to exporting, does make the whole workflow process a bit nicer ;)

 

 

 

 

 

 

Display Layers

Render Layers

File IO in the Maya API

Using MGlobal

Making Maya Work With Version Control (CVS/VSS)

Adding custom mel functions into Maya

Automating A Graphics Build Using mel

A Documentation System for Maya

 

   
Exporter Tips
 

 

Writing a stable and flexible exporter is often something fraught with problems. There are however a few tips that may make the process a little easier.

 

 

Building an Export List

Accessing custom plugin nodes

   
Source Code Examples
 

 

These source code examples provide a number of working examples of differing levels of exporter complexity. The Simple exporter basically replicates the same level of functionality as the obj exporter. The intermediate version adds support for Materials, Lights and Texture Data. The advanced Exporter Adds support for Nurbs, skinning and animation data, whilst the Uber-Advanced Exporter covers everything documented here, and provides a simple scripted extension interface.

 

The final source example cuts out the export stage completely by simply using the Maya API as it's scenegraph and using openGL to render it. A quirky idea, but one that may prove useful for simple editors etc.

 

 

 

 

 

 

 

Maya API Links

www.davidgould.com

www.highend3d.com

www.aliaswavefront.com

www.ewertb.com/maya

gpExport - a similar site to this one
(cheers to florain Loitsch for the link.
He has a better method of extracting the bind pose than mine)

Exporter Article on gamedev.net

hohehohe2's Open Maya Tutorial