Model Description (*.drmdl File) |
This topic describes the purpose and structure of the model description (*.drmdl file).
This topic contains the following sections:
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:
<?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 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.
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.
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" |
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" |
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>
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" |
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:
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>
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.
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 |
---|
The automatic generation of missing model descriptions can be turned off using a property of the content processor. |