Quickstart

Introduction

The Open Model Implementation for XNA is an alternative to the built-in Model class. It is based on the COLLADA file format and thus provides the corresponding content importer and processor classes. On top of that a custom Model implementation is used to render and animate the models.

At its core there are only two class libraries:

ColladaImporter

The ColladaImporter library offers a content importer and processor for loading the custom ModelData from COLLADA ".dae" files. Right now it is not compatible with the built-in XNA model class. However, a importer for this is relatively easily implemented based on the custom COLLADA content importer.

Primarily this library is intended to be used as part of a Visual Studio content project, which automatically selects the content importer and processor classes for ".dae" files, to compile the models at build-time, which then quickly can be loaded from binary xnb files at run-time. Since the ColladaImporter library uses the full .NET 4 framework (not the client profile), it can not be used in games directly.

However, there is a RuntimeLoader class that allows for loading COLLADA models completely at run-time without compiling xnb files. This can be used in developer applications such as level editors or asset viewers. An example for this usage is included in the project ColladaViewer.

ColladaModel

The ColladaModel library contains the common data model and classes for rendering and animating the 3D models. This library must be included in the game project to enable loading and rendering the 3D models.

It is distinguished between the model's data and the model renderer:
  • ModelData contains all the data loaded from the COLLADA file
  • StaticModel renders static geometry
  • SoftwareSkinnedModel renders animated models with Skinned Mesh Animation calculated on the CPU (i.e. not hardware accelerated)

Usage

The SampleGame and ColladaViewer projects included in the Visual Studio solution demonstrate usage of the libraries. Both represent two different usage scenarios. The ColladaViewer project relies on the DotNetZip Library for loading zipped folders containing COLLADA files and textures.

Usage in Games

Using the libraries in games is the classic scenario.

Setup

  1. Add the ColladaImporter library to your content project (http://msdn.microsoft.com/en-us/library/ff434572.aspx)
  2. Add the ColladaModel library to your game project (see above)
  3. Add a COLLADA ".dae" file to your content project (http://msdn.microsoft.com/en-us/library/bb313966.aspx)

Visual Studio should automatically select the correct importer and processor for the COLLADA model.

Application

When the model is part of the content project of the game it can be loaded as follows:

        /// <summary>
        /// LoadContent will be called once per game and is the place to load
        /// all of your content.
        /// </summary>
        protected override void LoadContent()
        {
            ModelData modelData = Content.Load<ModelData>("my_collada_model");
            IModel model = null;

            // Check if model has animations
            if (modelData.JointAnimations.Any())
            {
                model = new SoftwareSkinnedModel(modelData);
            }
            else
            {
                model = new StaticModel(modelData);
            }            
        }

Rendering the model is simply a matter of calling the IModel.Draw() method:

        /// <summary>
        /// This is called when the game should draw itself.
        /// </summary>
        /// <param name="gameTime">Provides a snapshot of timing values.</param>
        protected override void Draw(GameTime gameTime)
        {
            GraphicsDevice.Clear(Color.CornflowerBlue);

            model.Draw(world, view, projection);

            base.Draw(gameTime);
        }

If the model contains animation data the animation can be performed as follows:

        /// <summary>
        /// Allows the game to run logic such as updating the world,
        /// checking for collisions, gathering input, and playing audio.
        /// </summary>
        /// <param name="gameTime">Provides a snapshot of timing values.</param>
        protected override void Update(GameTime gameTime)
        {
            if (model is SoftwareSkinnedModel)
                (model as SoftwareSkinnedModel).
                    PlayFirstAnimation(gameTime.ElapsedGameTime.Milliseconds / 1000.0f);            

            base.Update(gameTime);
        }

Models exported from 3ds Max, which was the primary tool used during development, export animations
as one long animation where the different clips are simply appended to each other. For this the PlayFirstAnimation
method can be used to simply play this sole animation.

Usage in Dev Tools

Development Tools may use classes that are not part of the .NET 4 client profiles and as such make use of the RuntimeLoader.

Setup

  1. Add the ColladaImporter and ColladaModel libraries to your project (http://msdn.microsoft.com/en-us/library/et61xzb3(v=VS.100).aspx)

Application

The only difference when using the RuntimeLoader is how the ModelData is loaded. For the rest refer to the explanations above.
A model can be loaded using the RuntimeLoader as follows:

        void LoadModels()
        {            
            RuntimeLoader loader = new RuntimeLoader(GraphicsDevice);
            ModelData modelData = loader.Load("path/to/model.dae");
        }

The runtime loader optionally can be provided with a ContentManager instance, and the Load method also optionally accepts ProcessingOptions.

Materials

By default shaders are generated for each material supporting the COLLADA common material profile, which includes the classic phong/blinn lighting model, and Normal Mapping (Dot3 Bump Mapping, Parallax Mapping, and Relief Mapping) through the custom "bump"-COLLADA extension used by 3ds Max. This allows for handling 3D models with simple materials easily. However, its flexibility is limited.

For this reason custom shaders through the COLLADA BRIDGE profile (http://www.khronos.org/files/collada_spec_1_5.pdf, p. 8-87) are supported, which for example is used by Nvidia FX Composer 2.

A simple example how custom shaders can be used with any model is included in the SampleGame content project (SampleGameContent/3ds max/Custom-Fx-Test/Custom-APC.DAE). Right now I do not know which DCC tools actually support exporting custom shaders to COLLADA, other than Nvidia FX Composer 2.

However, you can add custom shaders to COLLADA files with a texteditor quite easily. For this, search for the effect definition in the COLLADA file (XPath: <library_effects> and simply add a custom technique containing a reference to the HLSL shader as follows:

    <effect id="myeffect">
      <profile_COMMON>...</profile_COMMON>
      <extra>
        <technique profile="NVIDIA_FXCOMPOSER">
          <import url="path/to/simple-shader.fx" compiler_options="" profile="fx"/>
        </technique>
      </extra>
    </effect>

The content importer implementation is a very simple one and thus is only looking for any file reference to a ".fx" file, so the technique's profile and position must not be the same, as long as it is contained in the effect tag.

Finally the shader parameters can be set within the material defintion (<library_materials>) as in the following example:

      <instance_effect url="#myeffect">
        <setparam ref="DiffuseMap">
          <surface type="2D">
            <init_from>apc_jpg</init_from> <!-- ID referring to <image> element in <library_images> -->
          </surface>
        </setparam>
        <setparam ref="FilterColor">
          <float4>1 1 0.5 1</float4>
        </setparam>
      </instance_effect>

Last edited Jun 3, 2011 at 10:40 PM by MathiasKahl, version 8

Comments

No comments yet.