Developing with Parameterized Processors

Describes how developing with parameterized processors, both standard and custom, requires additional thought and care. This topic discusses a method for programmatically modifying existing parameter values, and for adding new parameters to your own processors.

Programmatically Setting Parameter Values

When you need to pass parameter values from one processor to another (also referred to as chaining), use the BuildAsset and BuildAndLoadAsset methods. Pass the parameter and its value using the ProcessorParameters argument of the respective function. For example, a custom model processor would invoke a second processor for model textures with a call to BuildAsset and pass any parameter values in the ProcessorParameters argument.

The following code example demonstrates this technique. First, add several parameters to a data dictionary:

      //create a dictionary to hold the processor parameter
      OpaqueDataDictionary parameters = new OpaqueDataDictionary();

      //add several parameters to the dictionary
      parameters.Add( "ColorKeyColor", Color.Magenta );
      parameters.Add( "ColorKeyEnabled", true );
      parameters.Add( "ResizeToPowerOfTwo", true );
    

After adding the necessary parameters, pass the dictionary to the chained processor:

      context.BuildAsset<TextureContent, TextureContent="">(
      texture, typeof( TextureProcessor ).Name,
      parameters,
      null,
      null );
    

This call passes all parameters (stored in parameters) to a texture processor.

Again, any parameters not recognized by the receiving processor are ignored. Therefore, if the parameter ColorKeyCode is entered into the dictionary as ColourKeyCode, it is ignored by the receiving processor.

Declaring Process Parameters

Adding one or more parameters to your custom processor requires additonal code in your processor's definition. Parameters support the following types:

• bool
• byte
• sbyte
• char
• decimal
• double
• float
• int
• uint
• long
• ulong
• short
• ushort
• string
• enum
• Vector2, Vector3, and Vector4
• Color

Parameters of other types are ignored by the processor.

Tip

Apply the Browsable attribute (with a value of false) to an individual parameter to prevent that parameter from being displayed in the Properties window.

The following code example defines a simple custom processor that switches the coordinate system of a model using a single parameter (called switchCoordinateSystem):

      public class SwitchCoordSystemProcessor : ModelProcessor
      {
      #region Processor Parameters
      private bool switchCoordinateSystem = false;

      [DisplayName("Switch Coordinate System")]
      [DefaultValue(false)]
      [Description("Switches the coordinate system of a model.")]
      public bool SwitchCoordinateSystem
      {
        get { return switchCoordinateSystem; }
        set { switchCoordinateSystem = value; }
      }
      //additional class code follows...
    

In this code, the SwitchCoordSystemProcessor class is derived from ModelProcessor. This indicates that the processor accepts a model as input. The next few lines declare a single property called SwitchCoordinateSystem of type bool. Note that every parameter must have a set method. The property also has several attributes applied to it:

Attribute name	Usage
DisplayName	Name of the property when it appears in the Properties window of XNA Game Studio. If not specified, the internal property name, declared in the source code, is used. For this example, "Switch Coordinate System" would be displayed.
DefaultValue	A user interface (UI) hint specifying the possible default value of the property. This value is used only as a UI hint; it will not be set on the property, nor will it override the default value declared in the code.
Description	Descriptive text displayed when you select the property in the Properties window of XNA Game Studio.

This completes the definition of the SwitchCoordinateSystem property.

In the next code example, the class definition is continued with an override of the Process method:

      //additional class code precedes...

      public override ModelContent Process(NodeContent input, ContentProcessorContext context)
      {
        if (switchCoordinateSystem)
        {
          Matrix switchMatrix = Matrix.Identity;
          switchMatrix.Forward = Vector3.Backward;
          MeshHelper.TransformScene(input, switchMatrix);
        }

        return base.Process(input, context);
      }
    

This code passes the SwitchCoordinateSystem property (declared earlier) value to TransformScene, which is a helper method that applies a transform to a scene hierarchy.

See Also

Adding New Content Types
Parameterized Processors