Use the MDt API

The MDt API is an example of how to use the Maya API. It is not the only method of obtaining Maya scene information from Maya. It is a combination of Maya API functions and executing MEL commands to get access to the data.

MDt API is not meant to replace Maya API in any way. It is grown and functions are added when deemed that something is of common interest to multiple uses. For example, not all of the Shader attributes are cached in the database. Those that are static and found to be used repeatedly are cached, but the API allows for the original Maya Object to be referenced to obtain additional data that is needed. It can be thought of as a higher level grouping function of common routines.

The two-stage process of generating the internal database and then running a translator with that data is a very general implementation. The scanning of the DAG tree and populating the internal database takes time. It is possible to write faster translators using the Maya API functions directly. The approach used for the VRML2 and other MDt based translators was to reduce the amount of work that had to be redone for each translator, and to reuse what was possible from pre-existing translators.

The VRML2, RTG, and GE2 game translators have been implemented as “file translators”. They could also be implemented as normal Maya MPxCommand plug-ins.

Structure of the internal database

The database that is generated by the walking of the DAG tree is controlled by user options that are set/defined in the option box of the file translators.

The information gathered for the database consists of:

Shapes, Groups, Materials, Textures, Lights, and Cameras

Controls

These options are described in the sections for each of the games translators using the MDt API.

There is a lot of flexibility in the settings that can be set. The source code is also supplied so that additional options can be added for local customizations.

The options are implemented in the file MDtLayer.cpp and the header file MDtExt.h. It is possible to add additional control flags to the source code and also modify the MEL option scripts to set/reset the options.

This would also then modify the MDt files that implement the particular area of interest for the option. The translator Option MEL script file would then be modified to pass the values of the options to the translator itself.

Shapes

Shapes are the basic transformation/joint/polygonal/NURBS geometry objects. Each “shape” has an associated number of parameters.

Transformations
Materials/Groups
Parents

Each shape also has an associated list of Groups. If the shape is a pure transformation/joint node then the number of groups will be Zero (for instance, no shader assignments). This usually only occurs when the hierarchy is set to FULL, or all of the transformations are flattened out, and geometry is associated with all of them.

Some API functions that operate using the Shape index are:

DtShapeGetCount() - returns the number of shape nodes found.
DtShapeGetMatrix(idx, *matrix) - returns the transformation matrix for shape idx, in the variable matrix

In general it is faster to use the geometry from the ByShape based functions rather than those of the ByGroup family. There isn’t a second copy of the data generated and passed by to the caller.

The Shape functions are found in the source file MDtShape.cpp.

Groups

Groups are subsets of its Shape, that are defined by multiple shader assignments to it. For a NURB object there would be at most 1 group. For polygonal objects there would be 1 group for each shader that is assigned to that object. If there are no shaders assigned to the polygonal object then the number of groups will be zero. In this case it is most likely to be a transformation node of some kind.

The ByGroup functions need to allocate memory to generate the lists that are returned. Since the API functions don’t know when that memory is no longer used, it is up to you to free it when done with the returned lists.

The MDtShape.cpp file implements these functions.

Materials

Materials are the shaders found in the DAG tree walk.

For each shader that is found, a reference is stored for it, and can be accessed by either “name” or ID number. From the reference it is possible to use the Maya API directly to obtain the shader parameters of interest.

The MDtMaterial.cpp file implements these functions.

Textures

Textures are the textures mapped for the shaders. By default, only the color and transparency textures are evaluated and a combined rgba file image is generated in memory. It is possible to enable extra processing to output all or most of the textures mapped on a shader, this is part of the “MultiTexture” option.

The MDtMaterial.cpp file implements these functions

Lights

Lights information is gathered and made available. Similarly to Materials, a reference is temporarily saved to access the light parameters of interest.

The MDtLights.cpp file implements these functions

Camera

Camera information is gathered and made available. Similarly to the Materials, a reference is temporarily saved to access the camera parameter of interest.

The MDtCamera.cpp file implements these functions

Utility

There are some utility functions that allow for decomposing matrices, and other general functions. This are found in the MDtLayer.cpp file along with the control options for the DAG walk processing

Animation

Obtaining animation data out of the MDt functions is the same as getting the non-animation data out.

When the DAG tree is walked for generating the internal database, the references that are saved are used to obtain the geometry/material information that is needed.

Iterating over a range of animation, it is then accomplished with the DtFrameSet(frame ) call which sets the current frame time. Maya automatically updates its dependency graph.

For each frame, DtFrameSet then updates the parameters that are wanted. Currently, this is mostly the geometry (vertices, normals, uvs) so the same function calls are reused to get the new frames geometry data.

The transformation data is obtained by referencing the transformation object. This data is not cached.

We recommend that you iterate over the animation range as few times as possible. See the following example:

for ( animation = start, to end )

	for ( shape = 0, to last Shape )

		get and save TRS data for shape

	next shape

next frame