Developing a Custom Importer 

This topic describes the process of developing custom importers to add support for new game asset types.

The XNA Framework Content Pipeline provides standard importers for the following types of digital content:

• Microsoft DirectX X files (.x)
• Autodesk FBX format (.fbx)

In addition to these standard importers, XNA provides an API that you can use to design your own custom importers. This API is used to implement a basic class that accepts a specified file type and then generate one or more managed C# classes for use in your managed code. Currently, the XNA Content DOM (Document Object Model) provides support for meshes, materials, textures, and animations. For more information on specific parts of the XNA API that support custom importers, see ContentImporter, MeshContent, MeshBuilder, and MeshHelper classes.

In addition to files containing standard graphics content, it is also possible to import custom types from any kind of file. However, there is no automatic support for custom objects beyond the standard objects previously mentioned. For these situations, the custom importer can either return a ContentItem with custom information in the opaque data, or a custom type you have previously developed.

Developing Your Importer Class

All importers must extend from the ContentImporter class and be marked with a ContentImporterAttribute. The attribute is used to notify the content pipeline what types of files this importer can read, as well as other properties.

For example, the following code specifies that the MyImporter class can process any file with an .x extension:

[ContentImporterAttribute( ".x" )]
public class MyImporter : ContentImporter<NodeContent>
{
     public override NodeContent Import( String filename, ContentImporterContext context )
     {
             // implementation here
     }
}
    

You can also specify multiple types for a single importer. The following code specifies a class that processes files with .bmp, .dds, and .tga extensions:

[ContentImporter (".bmp",".dds",".tga")]
public class MyTextureImporter : ContentImporter<NodeContent>
{
     public override NodeContent Import( String filename, ContentImporterContext context )
     {
             // implementation here
     }
}
    

The content pipeline searches for classes matching these requirements in all pipeline assemblies available to the project. When the game is built, the Import function of the custom importer is called once for each XNA content item in the current project.

The custom importer should then parse the input file for types it can import, import them, and then return the imported object or objects.

The object type returned depends upon the file type that was read. It is recommended that your custom importer return types supported by the Content DOM of the content pipeline. This ensures interoperability with existing content pipeline components, including processors, readers (implemented with ContentTypeReader), and writers (implemented with ContentTypeWriter). For example, an importer that accepts .gif files would return a TextureContent object and an importer that accepts 3D files with meshes, models, and other hierarchical graphics data would return the root of the scene as a NodeContent object. For all data types returned by the custom importer, there must be a processor that accepts that type as input.

There are several properties and classes that are particularly useful when using NodeContent objects to represent a 3D scene or mesh. The Children property represents hierarchical information. The Transform property contains the local transform of the 3d object. The MeshContent class (a subclass of NodeContent) is used to represent meshes. The content pipeline provides two classes that make it easier to create and work with MeshContent objects. The MeshBuilder class creates new MeshContent objects when necessary and the MeshHelper class implements useful operations on existing MeshContent objects.

For more information, see Recommendations for Developing Custom Importers.

See Also

Recommendations for Developing Custom Importers