Share via

XNA Content Pipeline Overview

  • Article

The Content Pipeline is a special set of assemblies included with XNA Game Studio that use MSBuild to compile game assets such as image and sound files into streamlined, pre-processed binary files called XNBs (so named for the fact that the file extension of the compiled version of a source file is changed to .xnb) which load quickly at run-time. The Content Pipeline is only available on Windows.  For XNA 4.0 it requires the full .NET Framework 4.0. Previous versions of the Content Pipeline require the full .NET Framework 2.0. The Content Pipeline requires the full .NET Framework due its use of MSBuild.

XNB files are platform-specific and are designed to be loaded using the XNA Framework's ContentManager class and related internal helper classes without the Content Pipeline assemblies. As such, content built with the XNA Content Pipeline can be used at run-time despite the fact that the Content Pipeline might not exist on the target platform. The Content Pipeline is not included with the XNA Framework Redistributable and the XNA Framework EULA prohibits the distribution of the Content Pipeline assemblies except as packaged with XNA Game Studio.

The Content Pipeline is invoked through a special project type called a "content project". Game assets are added to the content project which is then referenced by one or more XNA game projects (XNA game projects are slightly customized .csproj files). The same content project can be shared by game projects targeting different platforms provided they are all targeting the same version of the XNA Framework. When built, assets in the content project will be compiled and written out to XNB files that are appropriate for the target platform of each game project which the content project is referenced by. This is one of many features of the XNA Framework that ease cross-platform development.

The Content Pipeline includes content importers and processors for many popular content creation tool export formats . Also, the Content Pipeline is fully extensible. This allows you to develop content importers and processors for any other file formats that your content tools export to provided that you have the specifications for the format and are not prohibited from doing so due to any legal considerations such as intellectual property rights and licensing agreements.

How It Works

The Content Pipeline operates as follows:

  1. The .contentproj file is read to find the next asset (if any) along with its specified importer and processor. (n.b. All importers inherit from ContentImporter<T>. All processors inherit from ContentProcessor<TInput,TOutput>.)
  2. An instance of the specified importer is created.
  3. The importer's Import method is called passing in the file name of the asset along with a ContentImporterContent (which provides a mechanism for returning warning and error messages). The asset specified by the file name is read either directly into the output object or else (if processing must be done to transform it into the output format) into an intermediate object of another type which will later be used to create the output object which Import returns.
  4. The Import method does minimal processing in order to determine if any other assets must be read in (e.g. texture maps and custom effects for a 3D model). If so it reads in each of the other assets (either directly or by creating an instance of the appropriate processor for that asset type and calling its Import method) and assigns them to the appropriate fields and properties within the intermediate object or the output object.
  5. Upon completion the Import method populates the output object from any intermediate objects if necessary and then returns the output object, which is fully loaded from the file system and ready for processing.
  6. An instance of the specified processor is created and its Process method is called, passing in as the input object the object that was returned from the importer's Import method along with an instance of the default implementation of the ContentProcessorContext abstract class.
  7. The Process method does whatever processing is required on the input object including creating a new instance of the output object and populating it appropriately if the type of the output object differs from the type of the input object.
  8. The Process method returns the output object.
  9. An instance of the ContentTypeWriter<T> for the type of the object returned from Process is instantiated and passed the object returned from Process along with a ContentWriter instance that is setup to write to the appropriate output file for the asset. ContentWriter is derived from BinaryWriter and includes methods for writing several XNA Framework value types and a few types that act to reference other assets. It also includes functionality for applying a general-purpose, lossless compression algorithm to the output depending on the platform and whether or not any meaningful amount of compression could be achieved. (n.b. Compression is never applied in Debug configuration, only in Release configuration.)
  10. The ContentTypeWriter<T> writes out the object in a target platform-appropriate way along with metadata indicating what the appropriate ContentTypeReader to read the object in at run-time is and what the run-time type of the object that is being written out should be. The build-time and run-time types sometimes differ due to how certain things must be addressed during build-time in order to avoid things like circular references and inappropriate dependence on the characteristics of the build-time platform.
  11. At run-time, when a request is made to an instance of the ContentManager class to load a specific XNB file using its Load<T> method, the ContentManager examines the file, checks to make sure the metadata specifying the run-time type matches the type T that was specified and then locates the ContentTypeReader that the metadata specifies and reads the file in, returning a reference to the object it has loaded while caching a reference internally to avoid loading the same asset multiple times and to speed subsequent requests (if any) for the same asset. This reference also enables the ContentManager to call Dispose on any objects it has loaded which implement IDisposable when the ContentManager's Unload method is called in order to prevent memory leaks from occurring.

Standard Importers

The standard importers that are included with XNA Game Studio are:

  • Autodesk FBX. Used to import 3D models that have been exported with the 2006.11 version of the Autodesk FBX exporter. The data is loaded in to an instance of the NodeContent class.
  • Effect. Used to import vertex and pixel shaders written in HLSL using the DirectX Effect file format. The data is loaded in to an instance of the EffectContent class.
  • MP3 Audio File. Used to import music and sound effects that are in MP3 format. The data is loaded in to an instance of the AudioContent class.
  • Sprite Font Description. Used to import .spritefont files, which are XML files that conform to the Sprite Font XML Schema. Sprite fonts are compiled into special bitmaps which are loaded into instances of the SpriteFont class at run-time. SpriteFont class instances are used in conjunction with the SpriteBatch class to draw strings within an XNA game. The data is loaded in to an instance of the FontDescription class.
  • Texture. Used to import textures. The supported file types are: .bmp; .dds; .dib; .hdr; .jpg; .pfm; .png; .ppm; and .tga. Depending on the file format and contents, the data will be loaded into an instance of either the Texture2DContent class, the Texture3DContent class, or the TextureCubeContent class. Unless you have taken explicit steps to create a 3D texture or a cube map, this will import your texture data into a Texture2DContent class instance.
  • WAV Audio File. Used to import music and sound effects that are in 16-bit PCM WAV format. The data is loaded in to an instance of the AudioContent class.
  • WMA Audio File. Used to import music and sound effects that are in WMA format. The data is loaded in to an instance of the AudioContent class.
  • WMV Video File. Used to import video clips that are in WMV format. There are restrictions of the encoding, which can be found here. The data is loaded in to an instance of the VideoContent class.
  • X File. Used to import 3D models that have been exported with the DirectX X File Format using a left-handed coordinate system. The data is loaded in to an instance of the NodeContent class.
  • XACT Project. Used to import game audio (both music and sound effects) that are in Microsoft Cross-Platform Audio Creation Tool. Although added to a content project, XACT projects are not built by the Content Pipeline's importers or processors. XACT is not available on Windows Phone 7.
  • XML Content. Used to import XML data in Intermediate format. The data is loaded in to an instance of the Object class.

Standard Processors

The standard processors that are included with XNA Game Studio are:

  • Effect Processor. Used to process instances of EffectContent. Returns an instance of EffectContent.
  • Font Description Processor. Used to process instances of FontDescription. Returns an instance of SpriteFontContent.
  • Font Texture Processor. Used to process custom sprite fonts created in conformance with the instructions here. Used to process Texture2DContent. Returns and instance of SpriteFontContent.
  • Model Processor. Used to process instances of NodeContent. Returns an instance of ModelContent.
  • No Processing Required (PassThroughProcessor). Used to process instances of Object. Returns the Object instance that was passed in without modification.
  • Song Processor. Used to process instances of AudioContent. Returns an instance of SongContent. Use this for game music and other background music.
  • Sound Effect Processor. Used to process instances of AudioContent. Returns an instance of SoundEffectContent. Use this for sound effects, such as a fog horn, a chime, or a door closing.
  • Texture Processor. Used to process instances of Texture2DContent, Texture3DContent, and TextureCubeContent. Returns the same type that was passed in.
  • Video Processor. Used to process instances of VideoContent. Returns an instance of VideoContent.

References

The following references will provide you with more information about the Content Pipeline.