Click or drag to resize
DigitalRuneModel Description (*.drmdl File)

This topic describes the purpose and structure of the model description (*.drmdl file).

This topic contains the following sections:

Model description (*.drmdl file)

The model description is an XML file with the file extension ".drmdl" or ".xml". It provides settings for processing a model and assigns materials to each submesh.

Example:

Model description: MyCharacter.drmdl
<?xml version="1.0" encoding="utf-8"?>

<Model File="MyCharacter.fbx"
       AabbMinimum="-1,-0.2,-1"
       AabbMaximum="1,2,1"
       GenerateTangentFrames="True"
       Scale="0.02">
  <Mesh Name="Body">
    <Submesh Material="Skin.drmat" />
    <Submesh Material="Cloth.drmat" />
  </Mesh>
  <Mesh Name="Hat">
    <Submesh Material="Hat.drmat" />
  </Mesh>
  <Animations ScaleCompression="0.01" 
              RotationCompression="1" 
              TranslationCompression="0.01">
  </Animations>
</Model>

When a model (e.g. a FBX file) is included in a content project, the DigitalRune model processor searches for a model description in the current folder. It looks for a file with the same name and the extension ".drmdl" or ".xml". For example, if the path of the model is "Assets\Models\Dude.fbx" the model description must be stored as "Assets\Models\Dude.drmdl".

If a model description is found, the model processor uses these settings for processing the model. If no matching model description is found, it uses the default settings.

In most cases the model (e.g. the FBX file) is added to content project. But when using model descriptions it is also possible to add the *.drmdl files instead of the models to the content project. The model description references the actual model using the File attribute as shown above. Adding the model descriptions instead of the model to the content project has the following advantages:

  • The model description can reference the model using an absolute or relative path. The model can be stored in a different folder.
  • In XNA it is usually not possible to import the same model multiple times. Multiple model descriptions can reference the same model. That means, it is possible to import and process the same model multiple times with different settings.
<Model>

The Model element has the following attributes:

Attribute

Description

Example

File

Optional: The path and name of the model file.

This attribute is only relevant when the .drmdl file is included in the content project instead of the actual model. The content pipeline will import the specified model as described below.

File="Dude.fbx"

AabbMaximum

Optional: The maximum corner for the axis-aligned bounding box (AABB) of the whole model.

AabbMaximum="2,2.5,1

AabbMinimum

Optional: The maximum corner for the axis-aligned bounding box (AABB) of the whole model. If both AabbMaximum and AabbMinimum are set, the default bounding shapes of all meshes are replaced with the specified AABB.

AabbMinimum="-2,-0.5,-1"

GenerateTangentFrames

Optional: If enabled, binormals and tangents are generated for all meshes. (Existing binormals and tangents remain unchanged - existing data is never removed or replaced.)

Allowed values are True and False.

The default value is False.

GenerateTangentFrames="True"

Importer

Optional: The type name of the content importer.

This attribute is only relevant when the .drmdl file is included in the content project instead of the actual model. The .drmdl file references the actual model and the content pipeline will import the model using the specified importer.

If the attribute is missing, the content pipeline will choose the default content importer based on the file extension of the model.

Importer="FbxImporter"

MaxDistance

Optional: The maximal distance up to which the model will be rendered.

See property SceneNodeMaxDistance.

The default value is 0, which means that distance culling is disabled.

MaxDistance="1000"

PremultiplyVertexColors

Optional: If enabled, the vertex colors are converted to premultiplied alpha format.

Allowed values are True and False.

The default value is True.

PremultiplyVertexColors="False"

RotationX

Optional: A rotation angle in degrees. The model is rotated by the specified number of degrees around the z-axis.

The default value is 0.

RotationX="90"

RotationY

Optional: A rotation angle in degrees. The model is rotated by the specified number of degrees around the y-axis.

The default value is 0.

RotationY="-90"

RotationZ

Optional: A rotation angle in degrees. The model is rotated by the specified number of degrees around the z-axis.

The default value is 0.

RotationZ="180"

Scale

Optional: A uniform scale factor, which is applied to the model.

The default value is 1.

Scale="0.1"

SwapWindingOrder

Optional: If enabled, the winding order of the faces is swapped.

Allowed values are True and False.

The default value is False.

SwapWindingOrder="True"

The Model element may have one or more Mesh elements and an optional Animations element.

<Mesh>

The model descriptions usually has one Mesh element per mesh in the original model. The Name attribute needs to be set to match the element with a mesh of the model. The Mesh element is used to specify processing options for the meshes and to assign materials to the submeshes.

The Mesh element is optional. If it is not specified, then the material processor tries to assign material using the texture names. For example, if an imported submesh uses a texture called Wood.tga, it will try to find a material definition file Wood.drmat in the folder that contains the texture. If a material definition is found, it is assigned to the submesh. If no material definition is found, the submesh will use the default material stored in the model.

The Mesh element has the following attributes:

Attribute

Description

Example

Name

The name of the mesh.

Name="Body"

GenerateTangentFrames

Optional: Specifies whether binormals and tangents are generated for this mesh. (Existing binormals and tangents remain unchanged - existing data is never removed or replaced.)

Allowed values are True and False.

The default value is False.

GenerateTangentFrames="True"

LodDistance

The LOD distance at which the mesh will be rendered. Only relevant if the mesh belongs to a LOD group.

The default value is 0.

LodDistance="50"

MaxDistance

Optional: The maximal distance up to which the mesh will be rendered.

See property SceneNodeMaxDistance.

The default value is 0, which means that distance culling is disabled.

MaxDistance="1000"

The Mesh element may contain one or more Submesh elements.

<Submesh>

The Submesh element assigns a material to each submesh. The order of the Submesh elements needs to match the order of the submeshes in the original model!

The Submesh element has the following attributes:

Attribute

Description

Example

GenerateTangentFrames

Optional: Specifies whether binormals and tangents are generated for this mesh. (Existing binormals and tangents remain unchanged - existing data is never removed or replaced.)

Allowed values are True and False.

The default value is False.

GenerateTangentFrames="True"

Material

The path of the material definition (*.drmat file).

Material="RustyMetal.drmat"

<Animations>

Any animations included in the model are automatically pre-processed and imported into the DigitalRune Graphics engine. The Animations element can be used to define further pre-processing options for animations.

The Animations element has the following attributes.

Attribute

Description

Examples

MergeFiles

Optional: A list of animation files, which are merged to the current model.

MergeFiles="idle.fbx;run.fbx;jump.fbx"

ScaleCompression

Optional: Enables key frame compression. The value is the max. allowed scale error of the compressed animation.

ScaleCompression="0.01"

RotationCompression

Optional: Enables key frame compression. The value is the max. allowed rotation error (in degrees) of the compressed animation.

RotationCompression="3"

TranslationCompression

Optional: Enables key frame compression. The value is the max. allowed translation error of the compressed animation.

TranslationCompression="0.001"

AddLoopFrame

Optional: Adds a copy of the first key frame at the end of the animation. This ensures that cyclic animations transition smoothly when the last key frame is reached.

When an animation is played back with LoopBehaviorCycle or LoopBehaviorCycleOffset the first key frame needs to match the last key frame. AddLoopFrame="True" inserts copy of the first key frame at time = duration. Existing key frames at time = duration are overwritten.

Allowed values are True and False.

The default value is False.

AddLoopFrame="True"

Animation compression

Key frame animations can be memory intensive at runtime - in particular if the exported animations store values for every frame. Animation compression can be applied to reduce the memory requirements at runtime.

Animation compression is a lossy type of compression. The quality of the resulting animation can be controlled by setting the attributes ScaleCompression, RotationCompression, and TranslationCompression.

Note, all three attributes have to be set to enable animation compression. For Example:

<?xml version="1.0" encoding="utf-8"?>

<Model File="Character.fbx">
  <Mesh Name="Body">
    <Submesh Material="Skin.drmat" />
    <Submesh Material="Cloth.drmat" />
  </Mesh>
  <Animations ScaleCompression="0.01" RotationCompression="1" TranslationCompression="0.01" />
</Model>
<Animation>

The Animations element can contain Animation elements, which can be used to split the animation.

The Animation element has the following attributes.

Attribute

Description

Examples

Name

The name of the animation.

Name="Walk"

StartTime

The start of the animation in seconds.

StartTime="0.0"

EndTime

The end of the animation in seconds.

EndTime="5.0"

StartFrame

The start frame (zero-based index) of the animation. The frame rate needs to be specified in the parent <Animations> tag.

StartFrame="0"

EndFrame

The end frame (zero-based index) of the animation. The frame rate needs to be specified in the parent <Animations> tag.

EndFrame="24"

AddLoopFrame

Optional: Adds a copy of the first key frame at the end of the animation. This ensures that cyclic animations transition smoothly when the last key frame is reached.

When an animation is played back with LoopBehaviorCycle or LoopBehaviorCycleOffset the first key frame needs to match the last key frame. AddLoopFrame="True" inserts copy of the first key frame at time = duration. Existing key frames at time = duration are overwritten.

Setting AddLoopFrame here overrides the settings in the <Animations> tag.

Allowed values are True and False.

The default value is False.

AddLoopFrame="True"

Multiple animations per model

The current Autodesk FBX exporter only supports a single animation take per FBX file. There are two ways to export and load a model with multiple animations:

  1. Merge animation files

    The first solution is to export the animations into different FBX files. Animations stored in external files can be merged to the model during pre-processing using the MergeFiles attribute.

    <?xml version="1.0" encoding="utf-8"?>
    
    <Model File="Character.fbx">
      <Mesh Name="Body">
        <Submesh Material="Skin.drmat" />
        <Submesh Material="Cloth.drmat" />
      </Mesh>
      <Animations MergeFiles="idle.fbx;walk.fbx;run.fbx;jump.fbx;turn.fbx" />
    </Model>
  2. Split animation

    The second solution is to concatenate all animations into a single animation take and export the animation take as part of the model. Animation tags can be used to split the take during pre-processing into individual animations.

    <?xml version="1.0" encoding="utf-8"?>
    
    <Model File="Character.fbx">
      <Mesh Name="Body">
        <Submesh Material="Skin.drmat" />
        <Submesh Material="Cloth.drmat" />
      </Mesh>
      <Animations Framerate="24"> <!-- Framerate attribute is only required if start and end are specified in 'frames'. -->      
        <Animation Name="Idle" StartTime="0" EndTime="1.0"/>   <!-- Start and end specified in seconds. -->
        <Animation Name="Walk" StartFrame="24" EndFrame="60"/> <!-- Start end end specified in frames. -->
        ...
    
      </Animations>
    </Model>

Note that either the first or the second approach can be used to import multiple animations. But it is not possible to mix both approaches.

Automatic creation of missing model description files

The DigitalRune model content processor will automatically create a default model description (*.drmdl file) if it cannot find any. You can edit this file to set the desired processing options and to assign materials to submeshes.

Note Note

The automatic generation of missing model descriptions can be turned off using a property of the content processor.

See Also