diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_Add_XML.md b/articles/getting_to_know/howto/content_pipeline/HowTo_Add_XML.md new file mode 100644 index 0000000..ed7745a --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_Add_XML.md @@ -0,0 +1,131 @@ +--- +title: How to add a custom XML Content File to a Project? +description: Describes how to add custom game data as an XML file through the Content Pipeline. +requireMSLicense: true +--- + +Custom game data that is expressed in an XML format can be easily integrated into your game through the MonoGame Content Pipeline. + +This example demonstrates the procedure for integrating custom XML data into the content project of a simple game for the Windows platform. + +> [!IMPORTANT] +> This tutorial assumes you are using Visual Studio as your IDE, for VSCode, follow [this guide from Microsoft](https://learn.microsoft.com/en-us/dotnet/core/tutorials/library-with-visual-studio-code?pivots=dotnet-8-0) for creating multi-project solutions from the command-line utilizing the MonoGame Project and MonoGame Class library templates. + +### To define game data + +Within the MonoGame solution, you create a new Windows Game Library project. + +1. Right-click the solution node, point to `Add`, click `New Project`, and then select the `MonoGame Game Library` template. + + > [!TIP] + > A `MonoGame Game Library` project is created instead of a Content Pipeline Extension Library project so that the class we will define can be used by both the [Content Importer](https://docs.monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.ContentImporter-1.html) that runs at build-time and the [Content Loader](xref:Microsoft.Xna.Framework.Content.ContentManager#Microsoft_Xna_Framework_Content_ContentManager_Load__1_System_String_) at game runtime. + + > [!IMPORTANT] + > For MonoGame `3.8.2` and below, make sure to keep the project at `.NET 6` or below. The MGCB tool for 3.8.2 CANNOT understand or read .NET 8 libraries as it is compiled with .NET 6. The Game project can use a higher version, but library projects must stay at `.NET 6` else they cannot be read. + +2. In the `Name` box, type `MyDataTypes`, and then click `OK`. + +3. In the `Solution Explorer`, delete the existing `Game1.cs` as it is not needed. + +4. `right-click` and select `Add -> Add New Item` to add a new class, call it `PetData.cs` + +5. Double click on `PetData.cs` and replace its contents with the following code to define the `PetData` class. + + ```csharp + namespace MyDataTypes + { + public class PetData + { + public string Name; + public string Species; + public float Weight; + public int Age; + } + } + ``` + +6. Build the `MyDataTypes` project for debug or release to generate the library's dll file (note which profile you used). + +### Add an XML file using the custom data to the game content + +In this procedure, the `MyDataTypes` library is added as a reference in the content project. + +1. Build the `MyDataTypes` project, making not of whether it is a `Debug` or `Release` build. + + > [!NOTE] + > It is recommended to always use the same built type for building library projects, as they normally only contain "types" it is safe to just build them as `Release`. The reason being that you cannot CHANGE the reference once made in the MGCB editor and it is not affected by the `Build Type` used to generate the project. + +2. In the `Solution Explorer` or your game project, `right-click` the game content folder, point to `Add`, and then click `New Item`. + +3. In the `Add New Item` dialog box, type `pets.xml` as the file name, and then click `OK`. + +4. Replace the contents of the template file with the following XML code: + + ```xml + + + + + Fifi + Dog + 11 + 6 + + + Bruno + Dog + 21 + 12 + + + Chloe + Cat + 6 + 3 + + + Pickles + Hamster + 0.4 + 1 + + + + ``` + + > [!TIP] + > TO learn how to generate the custom MonoGame XML content from your own classes, refer to the [How to Generate custom XML](HowTo_GenerateCustomXML.md) guide. + +5. Open the `MGCB Editor` from the `Game` project (not the library) by selecting the `.mgcb` file and either Double-clicking it (Visual Studio) or Right-clicking it and selecting `Open` (VSCode). + + > [!TIP] + > If you have any issues opening the MGCB content project, please refer to the [How to load content](HowTo_GameContent_Add.md) guide. + +6. In the `MGCB Editor`, select the "Content" node and the top and then locate the `References` section in the `Properties` window, as shown below: + + [MGCB Editor window properties](./images/mgcb_editor_content_properties_referencesSelected.png) + +7. Click the `References` VALUE field and a new window should pop up allowing you to manage the references for the MGCB project: + + [MGCB editor references window](./images/mgcb_editor_references_window.png) + +8. In the `Reference Editor` window, click `Add`, and navigate to the `MyDataTypes` project and locate the built `dll`, normally under `bin/release/net8.0` (or DEBUG if you use the debug build). Once selected, click `Open` and the reference should be added to the Reference Editor as shown above. + + > [!TIP] + > If the folder is empty, return to visual studio and build the `MyDataTypes` project, if it is not built, there is no dll. + > And make sure to choose either the `debug` or `release` folder depending on how the class library is built. + +9. Click on `Add Existing` from the `Edit -> Add` options in the menu (or the `Add Existing` toolbar button) and select the `pets.xml` file. + +When you press `F6` to build the solution, it should build successfully, including the custom game content imported from the XML file. + +> [!IMPORTANT] +> Adding the the class library of the data types project to the Content project is critical, else the Content Pipeline does not know how to serialize or deserialize the custom data you have defined. +> Although it is possible to simply serialize `value types` or `value type arrays` without this step. + +To load the data at runtime, see the tutorial [Loading XML Content at Runtime](HowTo_Load_XML.md). + +## See Also + +- [Using an XML File to Specify Content](HowTo_UseCustomXML.md) +- [Adding Content to a Game](HowTo_GameContent_Add.md) diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_ExtendFontProcessor.md b/articles/getting_to_know/howto/content_pipeline/HowTo_ExtendFontProcessor.md new file mode 100644 index 0000000..c387058 --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_ExtendFontProcessor.md @@ -0,0 +1,206 @@ +--- +title: How to Extend the Font Description Processor to Support Additional Characters? +description: Describes the process of developing a custom content processor needed to add additional characters to a FontDescription object based on the text that is required by the game. +requireMSLicense: true +--- + +In a font description (.spritefont) file, the `` area can be used to add additional characters to a font description. This enables you to use a [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont) to render an additional range of characters. + +For some languages, this approach is not ideal. For example, Chinese and Japanese both have many thousands of characters. Adding the full range of characters to `` dramatically increases the size of the font asset and the time required to build the font asset. A better solution adds individual characters whenever the specific characters are needed. You can create a custom content processor to implement this solution. + +In this example, a file called _messages.txt_ contains all the text rendered by the game. The custom processor adds all the characters contained in the text in this file to a [FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription). Then it processes the object in the standard way using the base [FontDescriptionProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor) functionality. All the characters in messages.txt will then be available to the [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont) object at run time. + +> [!IMPORTANT] +> This tutorial assumes you are using Visual Studio as your IDE, for VSCode please adapt the IDE interactions appropriately. + +## Using the Font Description Processor + +1. create a new MonoGame project called `FontGame` using the MonoGame template of your choice (for simplicity choose a desktop template) + +2. Add a new `SpriteFont` called `DefaultFont` to a game project by opening the MGCB Editor, then right-click the `Content` node, click **Add**, and then click **New Item**. + +3. Add the new SpriteFont to the game by selecting the **SpriteFont Description (.spritefont)** template, name the font `DefaultFont` and then click **Add**. + + ![Adding the `DefaultFont` SpriteFont](./images/mgcg_editor_new_spritefont.png) + +4. Modify this file to use an existing font and any additional characteristics you prefer. + + For more information, see [Sprite Font XML Schema Reference](../../whatis/Content_Pipeline/CP_SpriteFontSchema.md). + +5. Add a new text file named `messages.txt` to the game project by right-clicking on the FontGame project node in Solution Explorer, click **Add**, and then click **New Item**. + +6. Select the **Text File** template, enter **messages.txt** for the file name, and then click **Add** to add the text file to the game. + +7. In the new text file, enter any messages that will be printed by the font described in the Sprite Font file. + + > We will use the method [File.ReadAllText](http://msdn.microsoft.com/en-us/library/ms143369.aspx) to read the text in this file. This method requires a carriage return ("\\r") or line feed ("\\n") after the last string, so be sure to follow the last line of text in the file with a carriage return or line feed. + +### To create the new content processor project + +The Content Pipeline is part of the build process and it is separate from your game code, therefore you need to create a new assembly that contains the code developed in this topic. Creating this new assembly project is the first step in developing a new processor. + +1. To add the new processor project to the game solution, go to Solution Explorer, right-click the **Solution** node, click **Add**, and then click **New Project**. + +2. In the dialog box, select the template **MonoGame Content Pipeline Extension (MonoGame Team))**, enter `MyFontProcessor` in the **Name** field, and then click **OK**. The new project automatically contains references to the MonoGame Framework run-time and design-time Content Pipeline assemblies. + +### To extend the font processor + +1. Open the `Processor1.cs` which is the template Content Processor example. + +1. Add the following lines of code, after the last `using` statement: + + ```csharp + using System.IO; + using System.ComponentModel; + ``` + +1. Remove the placeholder code that assigns the processor input (`TInput`) and output (`TOutput`) types, including the `Process" method. They will not be needed. + +1. Change the base class of `Processor1` from [ContentProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline) to [FontDescriptionProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor), which identifies it as a SpriteFont processor. + + > [NOTE] + > You can read all about the different types of built-in processors in the API docs [Content.Pipeline.Processors](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors) + +1. Change the class name and the Processor display name to something a little more unique, so that we know which processor we are selecting, from "Processor1" to "**MyFontProcessor**". + + ```csharp + [ContentProcessor(DisplayName = "MyFontProcessor")] + internal class MyFontProcessor : FontDescriptionProcessor + ``` + +1. Add a new processor parameter (property) to the the class declaration and adorn it with [C# Attributes](https://learn.microsoft.com/en-us/dotnet/csharp/advanced-topics/reflection-and-attributes/) to state additional processing parameters for the property. + + This parameter stores the name of the text file that stores the messages displayed by the game. + + ```csharp + [DefaultValue("messages.txt")] + [DisplayName("Message File")] + [Description("The characters in this file will be automatically added to the font.")] + public string MessageFile + { + get { return messageFile; } + set { messageFile = value; } + } + private string messageFile = @"../messages.txt"; + ``` + + > [!NOTE] + > As the "messages.txt" file is not in our content project, we need to supply a path "relative" to the "Content" project where the Content Processor is running from. + > Hence the path to the file is denoted as `@"../messages.txt"`. + +1. Add a new [Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontTextureProcessor) method override to match the following code: + + ```csharp + public override SpriteFontContent Process(FontDescription input, ContentProcessorContext context) + {} + ``` + + This modification replaces the template parameter and return types with the proper types needed for the extended font processor. + +1. Inside the `Process` method, register a Content Pipeline dependency on `messages.txt`, which will read specifically from a file by that name from the Game Project. + + This dependency tells the Content Pipeline that if messages.txt changes, the font must be rebuilt. + + ```csharp + string fullPath = Path.GetFullPath(MessageFile); + + context.AddDependency(fullPath); + ``` + +1. Next, we add functionality to read the contents of the file and add each letter to the input font one by one. Note that the [Characters](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription) collection keeps track of duplicates automatically, it is not necessary for the user to make sure that each letter is added only once. The **Characters** collection will contain only one instance of each character, no matter how many times **Add** has been called. + + ```csharp + string letters = File.ReadAllText(fullPath, System.Text.Encoding.UTF8); + + foreach (char c in letters) + { + input.Characters.Add(c); + } + ``` + + > [!NOTE] + > In this example, messages.txt has been saved with Unicode UTF-8 encoding, which is the default encoding format that is specified in the call to [File.ReadAllText](http://msdn.microsoft.com/en-us/library/ms143369.aspx). However, the default file encoding format for text files that have been added to a Visual Studio project is `Western European (Windows) encoding`, corresponding to code page `1252`. If your text file uses a different encoding, specify the character encoding as follows: + + ```csharp + string letters = File.ReadAllText( fullPath, System.Text.Encoding.GetEncoding( 1252 ) ); + ``` + +1. Finally, call the `Base` **Process** method of the [FontDescriptionProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor) to build the font with the newly requested characters. + + ```csharp + return base.Process(input, context); + ``` + +Done. If your txt file is located elsewhere, make sure to update the path to the file appropriately, FROM the content project folder in the Processor project. + +Final code: + +```csharp +using Microsoft.Xna.Framework.Content.Pipeline; +using Microsoft.Xna.Framework.Content.Pipeline.Graphics; +using Microsoft.Xna.Framework.Content.Pipeline.Processors; +using System.ComponentModel; +using System.IO; + +namespace FontProcessor +{ + [ContentProcessor(DisplayName = "MyFontProcessor")] + internal class MyFontProcessor : FontDescriptionProcessor + { + public override SpriteFontContent Process(FontDescription input, ContentProcessorContext context) + { + string fullPath = Path.GetFullPath(MessageFile); + + context.AddDependency(fullPath); + string letters = File.ReadAllText(fullPath, System.Text.Encoding.UTF8); + + foreach (char c in letters) + { + input.Characters.Add(c); + } + return base.Process(input, context); + } + + [DefaultValue("messages.txt")] + [DisplayName("Message File")] + [Description("The characters in this file will be automatically added to the font.")] + public string MessageFile + { + get { return messageFile; } + set { messageFile = value; } + } + private string messageFile = @"../messages.txt"; + } +} +``` + +### Associate the custom font processor with the sprite font in the MGCB tool + +1. Compile the solution to build **MyFontProcessor**, as you need to add your custom font processor as an available content processor for the content pipeline. + +1. Open the MGCB tool for your `Content` project, click (select) the **Content** node, navigate down to the properties section and then click in the **References** property. + + [MGCB Editor window properties](./images/mgcb_editor_content_properties_referencesSelected.png) + +1. Navigate to the `dll` for the built `MyFontProcessor` project (which by default is in `\FontGame\MyFontProcessor\bin\debug\net6.0`), select it and click "open". + + > [IMPORTANT] + > Ensure that the processor project is always up to date when the main game is built, you need to create a project dependency. Also use either "debug" or "Release" build types for the processor project, the MGCB tool will NOT dynamically select it when you change the Projects build type. + +1. Build the Content Project to ensure everything is connected as it should be. + +1. Select the `.spritefont` file, and then in the **Properties** window change the `processor` to`MyFontProcessor` in the drop-down list associated with the **ContentProcessor** field. + +When you build the solution, the new processor adds the characters in the messages.txt file to the list of characters available to the [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont). + +> [!NOTE] +> To debug a Content Pipeline importer or processor, add the following line to the processor code to launch the debugger. +> +> ```csharp +> System.Diagnostics.Debugger.Launch(); +> ``` + +## See Also + +[Extending a Standard Content Processor](./HowTo_Extend_Processor.md) +[Adding New Content Types](../../whatis/Content_Pipeline/CP_Content_Advanced.md) diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_Extend_Processor.md b/articles/getting_to_know/howto/content_pipeline/HowTo_Extend_Processor.md new file mode 100644 index 0000000..6ac669f --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_Extend_Processor.md @@ -0,0 +1,135 @@ +--- +title: How To Extend a Standard Content Processor? +description: Describes how MonoGame lets you modify or extend the behavior of any standard Content Pipeline processor that ships with the product. +requireMSLicense: true +--- + +MonoGame lets you modify or extend the behavior of any standard Content Pipeline processor that ships with the product. See [Standard Content Importers and Content Processors](../../whatis/Content_Pipeline/CP_StdImpsProcs.md) for a description of standard processors. + +Because there are so many asset variants supported by different digital content creation (DCC) tools, it is often useful to be able to modify how one of the standard processors operates. The following examples illustrate some of the kinds of things you might want to do. + +> [!TIP] +> The following code samples are provided only for demonstration. Most of the functionality described is already available by using parameters on a standard processor. + +## Adding a Scaling Operation to a Processor + +There are many reasons why you might want to modify the existing functionality of a standard processor. Here is one example. If your source assets and your game are at different scales, you may want the processor to scale each model automatically at build time. You can implement such automatic scaling by overriding the [Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) method of the [ModelProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) class, which generates a [Model](xref:Microsoft.Xna.Framework.Graphics.Model). In the override, you first scale the entire scene, and then invoke the base class functionality to process as usual. + +The following code illustrates this technique: + +```csharp + [ContentProcessor] + class ScalingModelProcessor : ModelProcessor + { + public override ModelContent Process( + NodeContent input, ContentProcessorContext context ) + { + MeshHelper.TransformScene( input, Matrix.CreateScale( 10.0f ) ); + return base.Process( input, context ); + } + } +``` + +## Generating Additional Data + +In some cases, you may want to add information to a game asset that a standard processor would not. For example, if a custom effect you want to apply requires tangent or binormal data, you can extend the standard model processor to build this additional data into the asset. To do this, you override the [Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) method of the [ModelProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) class. In the override, navigate the [NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent) hierarchy of the game asset, and call [CalculateTangentFrames](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshHelper) for each [MeshContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshContent) object you find. + +The following code shows how to do this: + +```csharp + [ContentProcessor] + class ModelProcessorWithTangents : ModelProcessor + { + public override ModelContent Process( NodeContent input, ContentProcessorContext context ) + { + GenerateTangentFramesRecursive( input ); + return base.Process( input, context ); + } + + private void GenerateTangentFramesRecursive( NodeContent node ) + { + MeshContent mesh = node as MeshContent; + if (mesh != null) + { + MeshHelper.CalculateTangentFrames( mesh, VertexChannelNames.TextureCoordinate( 0 ), + VertexChannelNames.Tangent( 0 ), VertexChannelNames.Binormal( 0 ) ); + } + + foreach (NodeContent child in node.Children) + { + GenerateTangentFramesRecursive( child ); + } + } + } +``` + +## Changing the Processors Called for Child Objects + +Another useful technique is to override a standard processor, and to change how child objects are processed just by changing the processors they use. + +Consider, for example, the hierarchy of calls through which textures in a model are processed: + +- The standard [ModelProcessor.Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) method is called to process a [NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent) object that represents the root of a scene. +- `ModelProcessor.Process` in turn calls the [ModelProcessor.ConvertMaterial](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) method once for every [MaterialContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MaterialContent) object used in the scene. +- `ModelProcessor.ConvertMaterial` in turn invokes the [MaterialProcessor.Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.MaterialProcessor) method on the [MaterialContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MaterialContent) object passed to it. +- `MaterialProcessor.Process` in turn calls the [MaterialProcessor.BuildTexture](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.MaterialProcessor) method once for each texture in the [MaterialContent.Textures](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MaterialContent.Textures) collection in the `MaterialContent` object passed to it. +- `MaterialProcessor.BuildTexture` in turn invokes the [ModelTextureProcessor.Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor) method on the [TextureContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent) object passed to it. + +One reason you may want to change how this works is that the `ModelTextureProcessor.Process` method applies texture compression to all textures it processes. This could be DXT1, DXT5, PVRTC, ETC1, RGBA4444 or ATITC depending on target your platform. If textures in your game assets are compressed already, you may want to avoid a second compression. + +> [!TIP] +> Not all platforms support all types of texture compression. For example DXT1/5 are generally only supported on Desktop graphics cards and some NVidia mobile graphics cards. PVRTC is only supported on iOS and some Android devices with PowerVR graphics cards, and ATITC is only supported on ATI graphics cards. Using the `Compressed` setting for `TextureCompression` for the Texture Processor will let the Pipeline pick the best compression for your target platform. + +### To prevent compression of textures during processing + +Here is how to prevent compression from being applied to model textures during processing. + +1. Create an override of the standard [MaterialProcessor.BuildTexture](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.MaterialProcessor) method, and invoke the [TextureProcessor.Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor) method, which does no compression, instead of `ModelTextureProcessor.Process`. +2. Create an override of `ModelProcessor.ConvertMaterial` that invokes your override of `MaterialProcessor.BuildTexture` instead of the standard one. + +The first of these overrides could be coded as: + +```csharp + [ContentProcessor] + class NoCompressionMaterialProcessor : MaterialProcessor + { + protected override ExternalReference BuildTexture( + string textureName, ExternalReference texture, ContentProcessorContext context ) + { + return context.BuildAsset( texture, "TextureProcessor" ); + } + } +``` + +There are several things to note about this code. + +- An [ExternalReference](xref:Microsoft.Xna.Framework.Content.Pipeline) is an asset object that is shared between multiple classes, such as a diffuse texture used by more than one material. When such an asset is specified, the Content Manager loads only one copy of the `ExternalReference` at run time and builds it only once, no matter how many references there are to it. +- The [ContentProcessorContext](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext)[BuildAsset](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) method lets you invoke a processor by name to build the content in an object. +- Although _textureName_, the first argument to `BuildTexture`, is ignored in the override above, you could use it if you wanted to process textures differently depending on normal maps or other criteria. + +Given the processor created by your first override above, you could code the second override: + +```csharp + [ContentProcessor] + class NoCompressionModelProcessor : ModelProcessor + { + protected override MaterialContent ConvertMaterial( + MaterialContent material, ContentProcessorContext context ) + { + return context.Convert( + material, "NoCompressionMaterialProcessor" ); + } + } +``` + +Because this override is processing `MaterialContent` objects in memory rather than `ExternalReference` objects, it uses the [ContentProcessorContext.Convert](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) function instead of [BuildAsset](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) to invoke the processor created by your first override. + +After building and installing your new `NoCompressionModelProcessor` (see [Adding a Custom Importer](../../whatis/Content_Pipeline/CP_AddCustomProcImp.md)), you can assign it to any models whose textures are already compressed and no further compression is applied. + +## See Also + +- [Adding New Content Types](../../whatis/Content_Pipeline/CP_Content_Advanced.md) +- [What Is Content?](../../whatis/Content_Pipeline/CP_Overview.md) +- [What is the Content Pipeline?](../../whatis/Content_Pipeline/CP_Architecture.md) +- [Standard Content Importers and Content Processors](../../whatis/Content_Pipeline/CP_StdImpsProcs.md) +- [Adding a Custom Importer](../../whatis/Content_Pipeline/CP_AddCustomProcImp.md) diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_GenerateCustomXML.md b/articles/getting_to_know/howto/content_pipeline/HowTo_GenerateCustomXML.md new file mode 100644 index 0000000..f5da995 --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_GenerateCustomXML.md @@ -0,0 +1,116 @@ +--- +title: How to create a custom XML File? +description: For complex game data, using a software tool to create and maintain these assets may be useful. Level tables, for example, might be easier to develop through a custom-level editor tool. +requireMSLicense: true +--- + +The [IntermediateSerializer](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) class of the MonoGame Framework can be employed by custom tools running under Windows to directly serialize game data to an XML file. + +An XML file generated in this way then can be included in the game project and imported by [XmlImporter Class](xref:Microsoft.Xna.Framework.Content.Pipeline.XmlImporter) as part of the Content Pipeline. Because [XmlImporter](xref:Microsoft.Xna.Framework.Content.Pipeline.XmlImporter) is actually a wrapper for [IntermediateSerializer](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer), it is certain that the XML file will be in the [correct format](../../whatis/Content_Pipeline/CP_XML_Elements.md) to be deserialized by the same facility. + +The [IntermediateSerializer](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) class is controlled through the `XmlWriter` class of the .NET Framework defined in `System.Xml`. The properties of the `XmlWriterSettings` class can be used to specify its output properties. + +The serializer produces its output according to these rules: + +- All public fields and properties are serialized; a separate XML element is used for each. +- Protected, private, or internal data is skipped. +- Get-only or set-only properties are skipped. +- Properties come before fields. +- If there is more than one field or property, these are serialized in the order they are declared. +- Nested types are serialized using nested XML elements. +- When the class derives from another, members of the base class are serialized before data from the derived type. + +## XML Serialization Example + +The following steps create a simple program that demonstrates how a program can use the [IntermediateSerializer](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) method [IntermediateSerializer.Serialize Generic Method](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) to serialize program data to an XML file. + +### Step 1: Create a New Project + +You will create a new project in Visual Studio. + +1. On the `File` menu, click `New`, and then click `Project`. + +2. In the `New Project` dialog box, ensure `Windows` is selected in the `Project types` pane, and then click `Console Application` in the `Templates` pane. + +3. Open the new project, then in the `Solution Explorer`, right-click the `Dependencies` folder, and then click `Manage NuGet Packages..`. + +4. Click on the `Browse` tab (if not selected) and search for the `MonoGame.Framework.Content.Pipeline` package, and then click `Install`. + + Accept any dialog prompts for Licenses or dependencies as they appear. + +5. Additionally, install the `MonoGame.Framework.DesktopGL` NuGet package which is required by the `Content.Pipeline` package. + +## Step 2: Add XML Serialization + +1. In the `Solution Explorer`, double-click `Program.cs` to edit it. + +2. Add `using` declarations for the System.Xml and Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate namespaces. + + ```csharp + using System.Xml; + using Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate; + ``` + +3. Define a class to serialize to XML with the properties you wish to store in your custom XML. + + ```csharp + namespace XMLSerializerTest + { + class MyData + { + public int elf = 23; + public string hello = "Hello World"; + } + } + ``` + +4. Within the function `Main` of the `Program` class, add the following code. This code employs [IntermediateSerializer.Serialize Generic Method](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) to serialize the `MyData` class as an XML file. + +```csharp + class Program + { + static void Main(string[] args) + { + MyData ExampleData = new MyData(); + + XmlWriterSettings settings = new XmlWriterSettings(); + settings.Indent = true; + + using (XmlWriter writer = XmlWriter.Create("example.xml", settings)) + { + IntermediateSerializer.Serialize(writer, ExampleData, null); + } + } + } +``` + +## Step 3: Generate XML + +1. Press F5 to build and execute the program. +2. Examine the `example.xml` file in the project's `bin\\Debug\\netx.0` folder. + +> [!NOTE] +> `netx.0` relates to the version of .NET your project is building under, `net6.0` for `.NET 6` and `net8.0` for `.NET 8` + +You should have an output that looks like the following: + +```xml + + + + 23 + Hello World + + +``` + +## See Also + +### Concepts + +- [Using an XML File to Specify Content](HowTo_UseCustomXML.md) +- [Adding Content to a Game](HowTo_GameContent_Add.md) + +## Reference + +- [IntermediateSerializer Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_Load_XML.md b/articles/getting_to_know/howto/content_pipeline/HowTo_Load_XML.md new file mode 100644 index 0000000..8ed66ed --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_Load_XML.md @@ -0,0 +1,92 @@ +--- +title: How to load XML Content at Runtime? +description: Describes how to load custom game data at game runtime through the Content Pipeline. +requireMSLicense: true +--- + +This example concludes the procedure begun in the tutorial [Adding an XML Content File to a Visual Studio Project](HowTo_Add_XML.md). + +Once custom game data is integrated as game content from an XML file through the Content Pipeline, it exists within your game runtime package in binary format. The data can be [loaded at runtime](HowTo_GameContent_Add.md) through the [ContentManager](xref:Microsoft.Xna.Framework.Content.ContentManager). + +> [!IMPORTANT] +> This tutorial assumes you are using Visual Studio as your IDE, for VSCode please adapt the IDE interactions appropriately. + +## Add a SpriteFont for testing + +While not essential for loading XML, in order to demonstrate the loaded data and write it to the screen, we will add a [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont) to enable the drawing of strings. + +1. In the `Solution Explorer`, Double-click the `Content.mgcb` in the `Content` folder to open the MGCB editor. + + > [!TIP] + > If you have any issues opening the MGCB content project, please refer to the [How to load content](HowTo_GameContent_Add.md) guide. + +2. Click on `Edit -> New Item`, then name the file `Font` and select `SpriteFont Description` as the type. Click on `Create` to finish. + +3. Save the content project and then continue. + +## To load the custom data in the game + +1. To add the `MyDataTypes` library as a reference in the game project, In the `Solution Explorer`, right-click the game project, click `Add Reference`, click the `Projects` tab, select `MyDataTypes`, and then click `OK`. + +2. Then in the `Solution Explorer`, double-click `Game1.cs` to edit it. + +3. Add the `using` declaration for the MyDataTypes namespace at the top of the file beneath the existing `usings` statements. + + ```csharp + using MyDataTypes; + ``` + +4. Add a data declaration for an array of type `PetData` after the other `private` variables in the `Game1` class. + + ```csharp + private PetData[] pets; + ``` + +5. In the [Game.LoadContent](xref:Microsoft.Xna.Framework.Game#Microsoft_Xna_Framework_Game_LoadContent) override function, load the custom content. + + ```csharp + protected override void LoadContent() + { + // Load the pet data table + pets = Content.Load("pets"); + } + ``` + + The custom game data now resides in the array of `PetData` objects. + +6. The data loaded from the XML file into the `PetData` array can be accessed normally as c# code, for example, the following `Draw` code will render the data from the XML file to the screen if found, else it will write a warning. + + ```csharp + protected override void Draw(GameTime gameTime) + { + GraphicsDevice.Clear(Color.CornflowerBlue); + + _spriteBatch.Begin(); + // Check if the XML data was loaded into the pets data array. + if (pets != null) + { + // For each pet, write its data to the screen. + for (int i = 0; i < pets.Length; i++) + { + var pet = pets[i]; + _spriteBatch.DrawString(Content.Load("Font"), $"{pet.Name} / {pet.Species}: Weight [{pet.Weight}] - Age: [{pet.Age}]", new Vector2(100, 100 + 20 * i), Color.White); + } + } + else + { + // If no data was loaded (or there was an error) write `No Pets found` to the screen. + _spriteBatch.DrawString(Content.Load("Font"), "No pets found", new Vector2(100, 100), Color.White); + } + _spriteBatch.End(); + base.Draw(gameTime); + } + ``` + +The result of loading the XML and rendering the data should display as follows: + +![XML data output](./images/HowTo_Load_XML_Final.png) + +## See Also + +- [Using an XML File to Specify Content](HowTo_UseCustomXML.md) +- [Adding Content to a Game](HowTo_GameContent_Add.md) diff --git a/articles/getting_to_know/howto/content_pipeline/HowTo_UseCustomXML.md b/articles/getting_to_know/howto/content_pipeline/HowTo_UseCustomXML.md new file mode 100644 index 0000000..6e818ce --- /dev/null +++ b/articles/getting_to_know/howto/content_pipeline/HowTo_UseCustomXML.md @@ -0,0 +1,41 @@ +--- +title: How to use an XML File to Specify Content? +description: Game assets managed through the Content Pipeline include graphic items such as textures, models and meshes; sound files such as dialogue or music; and custom data that governs the behavior of the game. +requireMSLicense: true +--- + +Data tables, for example, are custom data that might describe different characters’ attributes or the features of each level in the game. The content and format of this data is specific to the requirements of the game. Custom game data in the form of an XML file also can be loaded into your game through the standard features of the Content Pipeline. + +When the Content Pipeline is used, the game does not have to parse the XML format in which the game data is originally stored. Data loaded by the game through [ContentManager](xref:Microsoft.Xna.Framework.Content.ContentManager) is read in deserialized form directly into a managed code object. + +## In This Section + +- [How to Add custom game data as an XML file](HowTo_Add_XML.md) + + Describes how to add custom game data as an XML file through the Content Pipeline. + +- [Generating a custom XML File](HowTo_GenerateCustomXML.md) + + Describes how to use [IntermediateSerializer](xref:Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.IntermediateSerializer) from a Windows application to generate XML content to add to a MonoGame application. + +- [Adding an XML Content File to a MonoGame Project](HowTo_GameContent_Add.md) + + Describes how to add custom game data as an XML file through the Content Pipeline. + +- [Loading XML Content at Runtime](HowTo_Load_XML.md) + + Describes how to load custom game data at game runtime through the Content Pipeline. + +- [XML Elements for XMLImporter](../../whatis/Content_Pipeline/CP_XML_Elements.md) + + Describes the elements of an XML file that can be processed by the [XmlImporter Class](xref:Microsoft.Xna.Framework.Content.Pipeline.XmlImporter). + +- [Sprite Font XML Schema Reference](../../whatis/Content_Pipeline/CP_SpriteFontSchema.md) + + Describes the valid tags and values for Sprite-Font (.spritefont) XML files used by the Content Pipeline to create [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont) textures. + +## See Also + +### Concepts + +[Adding Content to a Game](./HowTo_GameContent_Add.md) diff --git a/articles/getting_to_know/howto/content_pipeline/images/HowTo_Load_XML_Final.png b/articles/getting_to_know/howto/content_pipeline/images/HowTo_Load_XML_Final.png new file mode 100644 index 0000000..dcaf0a3 Binary files /dev/null and b/articles/getting_to_know/howto/content_pipeline/images/HowTo_Load_XML_Final.png differ diff --git a/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_content_properties_referencesSelected.png b/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_content_properties_referencesSelected.png new file mode 100644 index 0000000..4f997d3 Binary files /dev/null and b/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_content_properties_referencesSelected.png differ diff --git a/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_references_window.png b/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_references_window.png new file mode 100644 index 0000000..ea7c29d Binary files /dev/null and b/articles/getting_to_know/howto/content_pipeline/images/mgcb_editor_references_window.png differ diff --git a/articles/getting_to_know/howto/content_pipeline/images/mgcg_editor_new_spritefont.png b/articles/getting_to_know/howto/content_pipeline/images/mgcg_editor_new_spritefont.png new file mode 100644 index 0000000..2d201b0 Binary files /dev/null and b/articles/getting_to_know/howto/content_pipeline/images/mgcg_editor_new_spritefont.png differ diff --git a/articles/getting_to_know/howto/content_pipeline/index.md b/articles/getting_to_know/howto/content_pipeline/index.md index 0e5cd60..0d5caef 100644 --- a/articles/getting_to_know/howto/content_pipeline/index.md +++ b/articles/getting_to_know/howto/content_pipeline/index.md @@ -4,4 +4,24 @@ description: A series of articles to answer common questions related to Content requireMSLicense: true --- -## Coming soon \ No newline at end of file +## In This Section + +- [How to add content](HowTo_GameContent_Add.md) + + Demonstrates how to add content, such as images or sounds, to your game. + +- [How to use custom XML](HowTo_UseCustomXML.md) + + Demonstrates how to use a custom XML File to Specify Content. + +- [How to Load content from a library](HowTo_LoadContentLibrary.md) + + Demonstrates how to create A localized game using alternative sets of text that are appropriate to the language and culture of the gamer. + +- [How to extend a content processor](HowTo_Extend_Processor.md) + + Describes how MonoGame lets you modify or extend the behavior of any standard Content Pipeline processor. + +- [How to Extend the Font Description Processor to Support Additional Characters](HowTo_ExtendFontProcessor.md) + + Describes the process of developing a custom content processor needed to add additional characters to a [FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription) object based on the text that is required by the game. diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_AddCustomProcImp.md b/articles/getting_to_know/whatis/content_pipeline/CP_AddCustomProcImp.md new file mode 100644 index 0000000..1e160c8 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_AddCustomProcImp.md @@ -0,0 +1,28 @@ +--- +title: What is a Custom Importer? +description: MonoGame provides standard importers and processors for a number of common file formats used to store such basic game assets as models, materials effects, sprites, textures, and so on. For a list of file formats supported by these standard importers and processors. +requireMSLicense: true +--- + +MonoGame provides standard importers and processors for a number of common file formats used to store such basic game assets as models, materials effects, sprites, textures, and so on. For a list of file formats supported by these standard importers and processors, see [Standard Content Importers and Content Processors](CP_StdImpsProcs.md). + +## To add a custom importer or processor to a game project + +This procedure assumes you have copied the new importer or processor to a local folder in the game project. + +1. Open the MonoGame Pipeline Tool. +2. Load the `.mgcb` file associated with your game. +3. Click on the `Content` node and in the `Properties panel` click on `References`. +4. Click the `Add` Button. +5. Navigate to the directory containing the assembly with the custom importer or processor, and then add it. +6. Save. + +> [!IMPORTANT] +> For MonoGame `3.8.2` and below, make sure to keep the project at `.NET 6` or below. The MGCB tool for 3.8.2 CANNOT understand or read .NET 8 libraries as it is compiled with .NET 6. The Game project can use a higher version, but library projects must stay at `.NET 6` else they cannot be read. + +The new importer or processor now appears as a choice in dialog properties for importing or processing a newly added game asset. + +## See Also + +- [Adding New Content Types](CP_Content_Advanced.md) +- [Standard Content Importers and Content Processors](CP_StdImpsProcs.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md new file mode 100644 index 0000000..45aa9f7 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Architecture.md @@ -0,0 +1,55 @@ +--- +title: What is the Content Pipeline Architecture? +description: The Content Pipeline is designed to be extensible, so that it can easily support new input file formats and new types of conversion. +requireMSLicense: true +--- + +The MonoGame Content Pipeline is a set of processes applied when a game that includes art assets is built. The process starts with an art asset in its original form as a file, and continues to its transformation as data that can be retrieved and used within a MonoGame game through the MonoGame Framework Class Library. + +The Content Pipeline is designed to be extensible, so that it can easily support new input file formats and new types of conversion. + +Most MonoGame developers can ignore the inner workings of the Content Pipeline. The most commonly used types of game assets and formats are inherently supported by MonoGame. However, if you are a game developer who needs to support a new file format or game-engine capability, it is useful to understand the stages of the Content Pipeline that transform an asset from a digital-content creation (DCC) output file to part of the game binary. + +## Content Pipeline Components + +A game asset is made available to an MonoGame game after it is added to the Content project. Once the asset is part of the game solution, it is included in the Content Pipeline. + +Processes fall into two types depending on when they execute: design time components and runtime components. + +### Design-Time Components + +The design-time components of the MonoGame Content Pipeline that process your game assets execute when you build your MonoGame game as an executable file. These processes perform the initial transformation of an asset from its digital content creation (DCC) format to a managed code object that your game can use upon execution. + +Design-time components use the [Content Pipeline Class Library](CP_Class_Library.md), which can be used and extended to create custom Content Pipeline design-time components. + +#### Content Importer + +A `_Content Importer_` converts game assets from a particular DCC file format into objects in the MonoGame Content Document Object Model (DOM) that standard Content Processors can consume, or into some other custom form that a particular custom Content Processor can consume. + +An Content Importer typically converts content into managed objects based on the Content DOM, which includes strong typing for such assets as meshes, vertices, and materials. A custom Content Importer, however, may produce custom objects for a particular custom Content Processor to consume. + +#### Content Processor + +A `_Content Processor_` takes one specific type of an imported game asset and compiles it into a managed code object that can be loaded and used by MonoGame games. + +Each Content Processor acts upon a specific object type. For example, the [Effect Processor](CP_StdImpsProcs.md#standard-content-processors) accepts only [EffectContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.EffectContent) objects, representing a DirectX Effect asset. + +When you include a game asset file in your MonoGame `.mgcb` file, its **dialog properties** page specifies the appropriate Content Importer and Content Processor. Thereafter, when you build your game (by pressing F5), the assigned Content Importer and Content Processor for each asset is invoked automatically. The asset is built into your game in a form that can be loaded at run time by your game. + +The managed code objects created by the Content Processor are serialized into a compact binary format (also referred to as an intermediate format) file with an .XNB extension by the Content Pipeline Content Compiler. This .XNB file is used by the runtime components of the Content Pipeline that assist your game in retrieving the transformed game assets. + +The format of data in the .XNB file is tightly coupled to the MonoGame Framework. It is not designed for use by other runtime libraries. + +### Runtime Components + +Runtime components of the Content Pipeline support loading and using the transformed game asset by your MonoGame game. These components use the [MonoGame library](../WhatIs_MonoGame_Class_Library.md), which can be extended to create custom components. + +## Content Loader + +When the game needs the game asset's managed code object, it must call the [ContentManager.Load](xref:Microsoft.Xna.Framework.Content.ContentManager) method to invoke the Content Loader, specifying the object type it expects. The Content Loader then locates and loads the asset from the compact binary format (.XNB) file into the memory space of the game where it can be used. + +## See Also + +- [What Is Content?](CP_Overview.md) +- [Adding New Content Types](CP_Content_Advanced.md) +- [Loading Additional Content Types](CP_Customizing.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Class_Library.md b/articles/getting_to_know/whatis/content_pipeline/CP_Class_Library.md new file mode 100644 index 0000000..d62c548 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Class_Library.md @@ -0,0 +1,42 @@ +--- +title: Content Pipeline Class Library +description: Content Pipeline Class Library Reference +requireMSLicense: true +--- + +The Content Pipeline class library is a library of classes, interfaces, and value types that are included in MonoGame. This library provides access to MonoGame Framework Content Pipeline functionality and is designed to be the foundation on which Content Pipeline–related applications, components, and controls are built. + +## Namespaces + +- [Microsoft.Xna.Framework.Content.Pipeline](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.html) + + Provides classes representing base types and building block functionality for use by more specialized object models, such as the Graphics DOM. + +- [Microsoft.Xna.Framework.Content.Pipeline.Audio](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.Audio.html) + + Provides intermediate classes and types for representing and manipulating graphics audio data. + +- [Microsoft.Xna.Framework.Content.Pipeline.Graphics](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.Graphics.html) + + Provides intermediate classes and types for representing and manipulating graphics data. + +- [Microsoft.Xna.Framework.Content.Pipeline.Processors](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.Processors.html) + + Provides base classes that represent processors used by the MonoGame Framework Content Pipeline when processing specific game asset types. + +- [Microsoft.Xna.Framework.Content.Pipeline.Serialization.Compiler](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.Serialization.Compiler.html) + + Provides base classes that represent compilers and writers used by the MonoGame Framework Content Pipeline when processing specific game asset types. + +- [Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate](https://monogame.net/api/Microsoft.Xna.Framework.Content.Pipeline.Serialization.Intermediate.html) + + Provides base classes that represent the creation and writing of intermediate content for game asset types processed by the XNA Framework Content Pipeline. + +- Microsoft.Xna.Framework.Content.Pipeline.Tasks + + Provides support for importing and processing game assets into the binary format that is used by the Content Loader of a game project. + +## See Also + +- [Adding Content to a Game](../../howto/content_pipeline/HowTo_GameContent_Add.md) +- [What Is Content?](CP_Overview.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Content_Advanced.md b/articles/getting_to_know/whatis/content_pipeline/CP_Content_Advanced.md new file mode 100644 index 0000000..fbb1e02 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Content_Advanced.md @@ -0,0 +1,43 @@ +--- +title: What are custom content types? +description: Content Builders and Processors can be customized to handle almost any content type. +requireMSLicense: true +--- + +The game asset build process is controlled by Content Pipeline importers and content processors. When you press `F5` (or `dotnet build`) to build a game created with MonoGame, the appropriate Content Pipeline importer and processor for each asset is invoked. Each asset then is automatically built into your game. + +The flexibility of this process enables you to create and update game assets using a variety of digital content creation (DCC) tools. MonoGame supplies importers for several popular export formats supported by DCC tools, and also lets you develop custom importers for other formats. + +## In This Section + +- [What is the Content Pipeline Architecture?](CP_Architecture.md) + + Describes the components and execution flow of the MonoGame Content Pipeline. + +- [Content Pipeline Document Object Model](CP_DOM.md) + + Describes the built-in object support features for assets in the Content Pipeline. + +- [Loading Additional Content Types](CP_Customizing.md) + + Describes the options for customizing the Content Pipeline to support nonstandard game assets or special-purpose needs. + +- [Tips for Developing Custom Importers and Processors](CP_Tips_For_Developing.md) + + Provides useful information about how to design and debug a custom Content Pipeline importer or processor. + +- [Adding a Custom Importer](CP_AddCustomProcImp.md) + + Describes how to add a custom processor or importer to an existing game solution. + +- [Extending a Standard Content Processor](../../howto/Content_Pipeline/HowTo_Extend_Processor.md) + + Describes how MonoGame lets you modify or extend the behavior of any standard Content Pipeline processor that ships with the product. + +- [Developing with Parameterized Processors](CP_CustomParamProcs.md) + + Describes how to develop with parameterized processors, both standard and custom. + +- [How to: Extend the Font Description Processor to Support Additional Characters](../../howto/Content_Pipeline/HowTo_ExtendFontProcessor.md) + + Describes the process of developing a custom content processor needed to add additional characters to a [FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription) object based on the text that is required by the game. diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_CustomParamProcs.md b/articles/getting_to_know/whatis/content_pipeline/CP_CustomParamProcs.md new file mode 100644 index 0000000..b4c8dfa --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_CustomParamProcs.md @@ -0,0 +1,116 @@ +--- +title: What are Parameterized Processors? +description: This topic discusses a method for programmatically modifying existing parameter values, and for adding new parameters to your own processors. +requireMSLicense: true +--- + +## Programmatically Setting Parameter Values + +When you need to pass parameter values from one processor to another (also referred to as chaining), use the [BuildAsset](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) and [BuildAndLoadAsset](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) methods. Pass the parameter and its value using the _processorParameters_ argument of the respective method. For example, a custom model processor would invoke a second processor for model textures with a call to [BuildAsset](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentProcessorContext) and pass any parameter values in the _processorParameters_ argument. + +The following code example demonstrates this technique. First, add several parameters to a data dictionary: + +```csharp + //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: + +```csharp + context.BuildAsset( + 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 additional 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](xref:Microsoft.Xna.Framework.Vector2), [Vector3](xref:Microsoft.Xna.Framework.Vector3), and [Vector4](xref:Microsoft.Xna.Framework.Vector4) +- [Color](xref:Microsoft.Xna.Framework.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): + +```csharp + 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](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.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 the MonoGame Pipeline tool. 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 the MonoGame Pipeline Tool.| + +This completes the definition of the `SwitchCoordinateSystem` property. + +In the next code example, the class definition is continued with an override of the [Process](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor) method: + +```csharp + //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](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshHelper), which is a helper method that applies a transform to a scene hierarchy. + +## See Also + +- [Adding New Content Types](CP_Content_Advanced.md) +- [Parameterized Content Processors](CP_StdParamProcs.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Customizing.md b/articles/getting_to_know/whatis/content_pipeline/CP_Customizing.md new file mode 100644 index 0000000..a752bba --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Customizing.md @@ -0,0 +1,58 @@ +--- +title: Loading Additional Content Types? +description: MonoGame provides the capability to extend Content Pipeline components that import and process almost any game asset file type. +requireMSLicense: true +--- + +MonoGame provides standard Content Pipeline components that import and process the most commonly used game asset file types. These file types include, for example, Content Importers for the Autodesk (.fbx) format and the DirectX (.x) format. A complete list of file types is available in the [Standard Content Importers and Content Processors](CP_StdImpsProcs.md) topic. Most digital Content creation (DCC) tools are capable of creating output in at least one of these standard formats. + +## Choosing to Customize + +A custom Content Importer is required for game assets available only in formats unsupported by MonoGame standard Content Importers. One may already be available from a third party. Custom Content Importers can be developed by DCC vendors, game-engine developers, and interested game hobbyists. Once a custom Content Importer is installed on your computer, you can associate art files with the Content Importer to invoke it when you build the art files (see [Adding a Custom Importer](CP_AddCustomProcImp.md)). + +You may need to write your own custom MonoGame Content Pipeline components to: + +- Support a new type of game asset or format from a DCC tool. +- Derive special-purpose content from another piece of content at the time the game is built. + +Here are some typical scenarios, and a summary of which Content Pipeline components require customization. + +|Component|When to customize|Output options| +|-|-|-| +|Content Importer|
  • A game asset created by a DCC tool is available only in a format unsupported by a MonoGame standard Content Importer.
|
  1. [Content Document Object Model](CP_DOM.md) (DOM) object that can be consumed by a standard Content Processor.
  2. A custom object that must be consumed by a custom Content Processor.
| +|Content Processor|
  • Must process the custom output of a custom Content Importer.
  • Needs to process the output of a standard Content Importer in a special-purpose way.
|
  1. A standard Content Processor output type.
  2. A custom Content Processor output type that must be consumed by a custom Content Loader at game run time.
| +|Content Loader|
  • Must load custom output of a customized Content Processor.
  • A custom Content Loader is implemented by extending the [ContentManager.Load](xref:Microsoft.Xna.Framework.Content.ContentManager) method to load the new custom data type.
    • |
    1. A standard MonoGame Framework class object.
    2. A custom class object.
    | + +## Customization Scenarios + +This section examines some typical examples where customization is needed, and illustrates which Content Pipeline components must be changed. + +### Supporting a New File Format + +In this example, a nonstandard file format contains information that can be represented by a standard Content DOM type. + +![Custom Importer DOM](../images/CP_CustomImporter.png) + +As illustrated, only a custom Content Importer that can read the nonstandard file format and output a Content DOM object (in this case, a **TextureContent** object) is required. The remainder of the Content Pipeline process can be performed by a standard Content Processor and Content Loader. + +### Creating Special-Purpose Data from Standard Objects + +For this example, a texture object that represents a map of normalized vectors derived from the original texture object is created. + +![Sprite Importer DOM](../images/CP_CustomImporter.png) + +Since the texture is contained in a standard format for the game asset, a standard Content Importer can be used to create the **TextureContent** object. A custom Content Processor (**NormalMapProcessor**) creates the special-purpose data, but uses the standard **TextureContent** class to contain the result so that it can be loaded by the standard Content Loader. + +## Supporting Custom Data from a Nonstandard Game Asset + +Illustrated in this example is a nonstandard game asset file containing data that does not correspond to any standard data types. + +![Custom Importer DOM](../images/CP_CustomData.png) + +To read the nonstandard game asset file, a custom Content Importer is required that outputs a **CustomContent** object. Since the output of the Content Importer is a custom class, a custom Content Processor also is needed, and the [ContentManager.Load](xref:Microsoft.Xna.Framework.Content.ContentManager) method must be extended to support the custom data object. + +## See Also + +- [Adding New Content Types](CP_Content_Advanced.md) +- [What Is Content?](CP_Overview.md) +- [What is the Content Pipeline?](CP_Architecture.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_DOM.md b/articles/getting_to_know/whatis/content_pipeline/CP_DOM.md new file mode 100644 index 0000000..3e52d36 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_DOM.md @@ -0,0 +1,20 @@ +--- +title: What is the Content Pipeline Document Object Model? +description: The MonoGame Content Document Object Model (DOM) represents the set of built-in classes that can be consumed by standard content processors. +requireMSLicense: true +--- + +The MonoGame Content Document Object Model (DOM) represents the set of built-in classes that can be consumed by standard content processors. + +Currently, the DOM provides support for meshes, materials, textures, sprite-fonts, and animations. Outside of these, a custom importer can return a [ContentItem](xref:Microsoft.Xna.Framework.Content.Pipeline.ContentItem) with custom information in its opaque data, or a custom type you have developed. + +The following diagram lists the complete Content DOM. + +![Content DOM](../images/ContentPipelineTypes_small.png) + +## See Also + +- [What Is Content?](CP_Overview.md) +- [What is the Content Pipeline?](CP_Architecture.md) +- [Extending a Standard Content Processor](../../howto/Content_Pipeline/HowTo_Extend_Processor.md) +- [Adding New Content Types](CP_Content_Advanced.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md b/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md new file mode 100644 index 0000000..e43bbc1 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Overview.md @@ -0,0 +1,68 @@ +--- +title: What Is Content? +description: Content is all the parts of your game that are not executing managed code. It includes all art assets, such as textures, sprites, meshes, effects, and fonts; and includes sound assets, such as music or brief sound effects. It also can include data assets, such as tables of levels or character attributes. +requireMSLicense: true +--- + +The MonoGame Content Pipeline is a set of processes applied to a game's art and data assets when the game is built. The process starts with an art asset in its original form as a file, and it continues to its transformation as data that can be retrieved and used within a MonoGame game through the MonoGame Framework Class Library. + +Content is all the parts of your game that are not executing managed code. It includes all art assets, such as textures, sprites, meshes, effects, and fonts; and includes sound assets, such as music or brief sound effects. It also can include data assets, such as tables of levels or character attributes. + +Most content will be created using a digital content creation (DCC) tool, such as a paint program or a 3D model editor. The content your game uses is stored in a variety of file formats. Most will be standard file formats, such as JPEG for textures or Autodesk FBX format for 3D models. However, they might also be in a custom format or house custom data in XML format. + +## Benefits of the Content Pipeline + +The chief reason MonoGame uses a Content Pipeline is to help your game run fast. Without the content pipeline, your game would have to be built with its art assets in their original file format. When the game needs to load its art to draw it on the screen, it would have to determine its format and convert the data into a form it can use more directly. This would have to be performed at run time, for each asset, making the player wait to have fun. + +The Content Pipeline remedies this by shifting this time-consuming work to when the game is built. At build time, each asset is imported from its original file format and processed into a managed code object. Those objects are then serialized to a file that is included in the game’s executable. + +At run time, the game can then read the serialized data from the file directly into a managed code object for immediate use. + +This architecture also provides several other benefits. + +- Game artists can use the DCC tools of their choice. +- Game developers can use the files game artists produce directly in their MonoGame projects. +- If all game assets are in file formats supported by the [Standard Importers and Processors](CP_StdImpsProcs.md) provided by MonoGame, the game developer never needs to be concerned with the specifics of that file format, nor possess a detailed knowledge of how the Content Pipeline works. +- If required, the Content Pipeline can easily be customized or extended to import a new file format or to produce custom output. + +## Using the Content Pipeline + +For MonoGame games that use the most common types of art assets and formats, a detailed knowledge of how the Content Pipeline works is unnecessary. MonoGame supplies standard importers and processors for many popular DCC file formats. The only procedure necessary is to add these assets to the game's content project. For a list of formats MonoGame inherently supports, see [Standard Content Importers and Content Processors](CP_StdImpsProcs.md). + +To use a DirectX Effect (.fx) file in your game, for example, just [add](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) the file to the MonoGame game content project (.mgcb). The MonoGame Pipeline tool recognizes the .fx file type as one it supports, and it assigns the correct components to it that are used to process it when the game is built. The game then can access the effect through the standard [ContentManager.Load](xref:Microsoft.Xna.Framework.Content.ContentManager) method of the MonoGame Framework. The game programmer does not need to be concerned about all the steps taken by the Content Pipeline to ready it for this straightforward use. + +There are other circumstances, however, when it helps to understand how the Content Pipeline works. + +- A third party may provide custom MonoGame Content Pipeline components that support additional art assets and formats. +- You may need to write your own custom MonoGame Content Pipeline components to support a new type of art asset or format from a DCC. +- You may wish to write your own custom MonoGame Content Pipeline components to derive special-purpose content from another piece of content at the time the game is built. + +## Content Pipeline Components + +The processes that comprise the MonoGame Content Pipeline fall into two types, depending on when they execute: build-time components and run-time components. + +### Build-Time Components + +The build-time components of the Content Pipeline that process your art assets execute within Visual Studio when you build your MonoGame game and produce an executable file. These processes perform the initial transformation of an asset from a DCC format to a managed code object that your game can use when it executes. + +These build-time components make use of the [Content Pipeline Class Library](CP_Class_Library.md), which can be used and extended to create custom Content Pipeline build-time components. + +|Component|Description| +|-|-| +|Importer|An _importer_ converts art assets from a particular DCC file format to objects in the MonoGame [Content Document Object Model](CP_DOM.md) that standard content processors can consume, or to some other custom form that a particular custom processor can consume.| +|Content processor|A _processor_ takes one specific type of imported art asset, such as a set of meshes, and compiles it into a managed code object that can be loaded and used by MonoGame games at runtime.| + +When you include an art asset file in your MonoGame solution's content project (.mgcb), its Properties page in the Pipeline tool specifies the appropriate importer and processor. Thereafter, when you build your game (by pressing F5), the assigned importer and processor for each asset is invoked automatically. The asset is built into your game in a form that can be loaded at run time by your game by using [ContentManager.Load](xref:Microsoft.Xna.Framework.Content.ContentManager). + +## Run-time Components + +The run-time components of the MonoGame Content Pipeline support the loading and use of the transformed art asset by your MonoGame. + +These run-time components make use of the [MonoGame Framework Class Library](../WhatIs_MonoGame_Class_Library.md), which can be extended to create custom Content Pipeline run-time components. + +## See Also + +### Concepts + +- [Adding Content to a Game](index.md) +- [Adding New Content Types](CP_Content_Advanced.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_SpriteFontSchema.md b/articles/getting_to_know/whatis/content_pipeline/CP_SpriteFontSchema.md new file mode 100644 index 0000000..5610f17 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_SpriteFontSchema.md @@ -0,0 +1,76 @@ +--- +title: What is Sprite Font XML Schema Reference? +description: Describes the valid tags and values for Sprite-Font (.spritefont) XML files used by the Content Pipeline to create SpriteFont textures. +requireMSLicense: true +--- + +## Sprite Font XML Schema Reference + +|Tag name|Content type|Content description| +|-|-|-| +|``|string|The name of the font to be imported. This is not the name of a font file, but rather the friendly name that identifies the font once it is installed on your computer. You can use the **Fonts** folder in Control Panel to see the names of fonts installed on your system, and to install new ones as well. The Content Pipeline supports the same fonts as the [System.Drawing.Font](http://msdn.microsoft.com/en-us/library/system.drawing.font.aspx) class, including TrueType fonts, but not bitmap (.fon) fonts.| +|``|float|The point size of the font to be imported.| +|``|float|The number of pixels to add between each character when the string is rendered.| +|``|Boolean|Specifies whether to use kerning information when rendering the font. Default value is **true**.| +|` + + + 32 + 127 + + + + +``` + +Here is a sample localized `.spritefont` file: + +```xml + + + + Courier New + 18 + 0 + true + + + + 32 + 127 + + + + Strings.resx + Strings-fr.resx + + + +``` + +## See Also + +- [Adding Content to a Game](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) + +### Reference + +- [SpriteFont](xref:Microsoft.Xna.Framework.Graphics.SpriteFont) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_StdImpsProcs.md b/articles/getting_to_know/whatis/content_pipeline/CP_StdImpsProcs.md new file mode 100644 index 0000000..f88b952 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_StdImpsProcs.md @@ -0,0 +1,47 @@ +--- +title: What are the Standard Content Importers and Content Processors? +description: Describes the standard Content Pipeline Content Importers and Content Processors of MonoGame that support various common art asset file formats. +requireMSLicense: true +--- + +Describes the standard Content Pipeline Content Importers and Content Processors of MonoGame that support various common art asset file formats. + +Content Importers and Content Processors are implemented as assemblies. In addition to the standard ones provided by MonoGame and listed below, you can also use custom Content Importers and Content Processors developed by you or third parties. Use the Properties window to assign an appropriate Content Importer and Content Processor to each game asset added to your game project. + +## Standard Content Importers + +The following is a description of the standard Content Importers shipped with MonoGame and the type of game asset each supports. + +All standard Content Importers are declared as part of the `Microsoft.Xna.Framework.Content.Pipeline` namespace. + +| Name | Type name | Output type | Description | +| ------------- |:-------------:| :----- | :---- | +| Autodesk FBX|FbxImporter|[NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)|Imports game assets specified with the Autodesk FBX file format (.fbx). This Content Importer is designed to work with assets exported with the 2013 version of the FBX exporter. | +| Effect|EffectImporter|[EffectContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.EffectContent)|Imports a game asset specified with the DirectX Effect file format (.fx). | +| Sprite Font Description|FontDescriptionImporter|[FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription)|Imports a font description specified in a .spritefont file.| +| Texture|TextureImporter|[TextureContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|Imports a texture. These file types are supported: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga.| +| X File|XImporter|[NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)|Imports game assets specified with the DirectX X file format (.x). This Content Importer expects the coordinate system to be left-sided.| +| XML Content|XmlImporter|object|Imports XML content used for editing the values of a custom object at run time. For instance, you could pass XML code to this Content Importer that looks for the specified property of a custom type and changes it to the specified value. You could then process the custom object with a Content Processor or pass it to your game untouched using the No Processing Required Content Processor.This Content Importer is designed for scenarios like importing an XML file that describes game data at run time (similar to the Sprite Font Description Content Importer) or importing terrain data in an XML file that then is passed to a Content Processor that generates a random terrain grid using that data.| +| Other 3D Content|OpenAssetImporter|[NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)|Imports game assets specified with one of the formats supported by assimp. A sample of supported files types are: .dae, .3ds, .blend, .obj, .fbx (v2013). More are available see [Assimp Supported File Formats](https://github.com/assimp/assimp#supported-file-formats) for more details. Note some formats might not behave correctly with the standard [ModelProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor).| + +## Standard Content Processors + +MonoGame ships with a variety of Content Processors that support several common game asset types. Many of the standard Content Processors, such as the [TextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor), support parameters for modifying the default behavior of the Content Processor. For more information, see [Parameterized Content Processors](CP_StdParamProcs.md). + +The following describes the standard Content Processors and the type of game asset each supports. + +| Name| Type name| Input type| Output type| Description| +| ----------------- |:-------------:| :----- | :---- | :---- | +| Model|[ModelProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor)|[NodeContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)|[ModelContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelContent)|A parameterized Content Processor that outputs models as a [ModelContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelContent) object.
    Available parameters:
    * Color Key Color–Any valid [Color](xref:Microsoft.Xna.Framework.Color). [Magenta](xref:Microsoft.Xna.Framework.Color) is the default value.
    * Color Key Enabled–A Boolean value indicating if color keying is enabled. The default value is **true**.
    * Generate Mipmaps–A Boolean value indicating if mipmaps are generated. The default value is **false**.
    * Generate Tangent Frames–A Boolean value indicating if tangent frames are generated. The default value is **false**.
    * Resize Textures to Power of Two–A Boolean value indicating if a texture is resized to the next largest power of 2. The default value is **false**.
    * Scale–Any valid [float](http://msdn.microsoft.com/en-us/library/system.single.aspx) value. The default value is 1.0.
    * Swap Winding Order–A Boolean value indicating if the winding order is swapped. This is useful for models that appear to be drawn inside out. The default value is **false**.
    * Texture Format–Any valid [SurfaceFormat](xref:Microsoft.Xna.Framework.Graphics.SurfaceFormat) value. Textures are either unchanged, converted to the Color format, or DXT Compressed. For more information, see [TextureProcessorOutputFormat](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessorOutputFormat).
    * X Axis Rotation–Number, in degrees of rotation. The default value is 0.
    * Y Axis Rotation–Number, in degrees of rotation. The default value is 0.
    * Z Axis Rotation–Number, in degrees of rotation. The default value is 0.| +|No Processing Required|[PassThroughProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.PassThroughProcessor)|Object|Object|Performs no processing on the file. Select this Content Processor if your content is already in a game-ready format (for example, an externally prepared DDS file) or a specialized XML format (.xml) designed for use with XNA Game Studio.| +|Sprite Font Description|[FontDescriptionProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor)|[FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription)|[SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent)|Converts a .spritefont file specifying a font description into a font.| +|Sprite Font Texture|[FontTextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontTextureProcessor)|[TextureContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|[SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent)|A parameterized Content Processor that outputs a sprite font texture as a [SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent) object.
    Available parameters:
    * First Character–Any valid character. The space character is the default value.| +| Sprite Font Texture|[FontTextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontTextureProcessor)|[Texture2DContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.Texture2DContent)|[SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent)|Converts a specially marked 2D bitmap file (.bmp) into a font. Pixels of **Color.Magenta** are converted to **Color.Transparent**.| +| Texture|[TextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor)|[TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|[TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|A parameterized Content Processor that outputs textures as a [TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent) object.
    Available parameters:
    * Color Key Color–Any valid [Color](xref:Microsoft.Xna.Framework.Color). [Magenta](xref:Microsoft.Xna.Framework.Color) is the default value.
    * Color Key Enabled–A Boolean value indicating if color keying is enabled. The default value is **true**.
    * Generate Mipmaps–A Boolean value indicating if mipmaps are generated. The default value is **false**.
    * Resize to Power of Two–A Boolean value indicating if a texture is resized to the next largest power of 2. The default value is **false**.
    * Texture Format–Any valid [SurfaceFormat](xref:Microsoft.Xna.Framework.Graphics.SurfaceFormat) value. Textures are either unchanged, converted to the Color format, or DXT Compressed. For more information, see [TextureProcessorOutputFormat](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessorOutputFormat).| +|Localized Sprite Font Texture|[LocalizedFontProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.LocalizedFontProcessor)|[FontDescription](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.FontDescription)|[SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent)|Converts a .spritefont file specifying a font description into a font.| + +## See Also + +- [Adding Content to a Game](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) +- [What Is Content?](CP_Overview.md) +- [Adding a Custom Importer](CP_AddCustomProcImp.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_StdParamProcs.md b/articles/getting_to_know/whatis/content_pipeline/CP_StdParamProcs.md new file mode 100644 index 0000000..e28cf0d --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_StdParamProcs.md @@ -0,0 +1,26 @@ +--- +title: What are the Parameterized Content Processors? +description: Describes how parameterized Content Processors work in MonoGame. +requireMSLicense: true +--- + +Describes how parameterized Content Processors work in MonoGame. Many of the standard Content Pipeline Content Processors shipped with XNA Game Studio support parameter usage. Parameterization makes any standard or custom Content Processor more flexible and better able to meet the needs of your XNA Framework application. In addition to specifying values for standard parameters, you can easily implement parameter support for a new or an existing custom Content Processor. For more information, see [Developing with Parameterized Processors](CP_CustomParamProcs.md). + +When you select a game asset, the Properties window displays the parameters for the related Content Processor. Use the Properties window at any time to modify these parameter values. + +> [!TIP] +> If you change the Content Processor for a game asset to a different Content Processor, all parameter values are reset to their default values. This means that if you modify the **Generate Mipmaps** parameter value for the [TextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor) and then switch to a different Content Processor (for example, [FontTextureProcessor Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontTextureProcessor)), the parameters switch to the default values for that Content Processor. If you then switch back again, the modified values are reset to the default values of the original Content Processor. _The values do not revert to the modified values you set originally_. + +## Standard Parameterized Content Processors + +The following describes only standard Content Processors that accept parameters, the parameter types, and their default value. For more information about all standard Content Processors, see [Standard Content Importers and Content Processors](CP_StdImpsProcs.md). + +| Friendly name| Type name | Input type | Output type | Description | +|-------------------|-----------|------------|-------------|------------------------------| +| Model | [ModelProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelProcessor)| [NodeContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)| [ModelContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelContent) |A parameterized Content Processor that outputs models as a [ModelContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.ModelContent) object.
    Available parameters:
    *Color Key Color–Any valid [Color](xref:Microsoft.Xna.Framework.Color). [Magenta](xref:Microsoft.Xna.Framework.Color) is the default value.
    * Color Key Enabled–A Boolean value indicating if color keying is enabled. The default value is **true**.
    *Generate Mipmaps–A Boolean value indicating if mipmaps are generated. The default value is **false**.
    * Generate Tangent Frames–A Boolean value indicating if tangent frames are generated. The default value is **false**.
    *Resize Textures to Power of Two–A Boolean value indicating if a texture is resized to the next largest power of 2. The default value is **false**.
    * Scale–Any valid [float](http://msdn.microsoft.com/en-us/library/system.single.aspx) value. The default value is 1.0.
    *Swap Winding Order–A Boolean value indicating if the winding order is swapped. This is useful for models that appear to be drawn inside out. The default value is **false**.
    * Texture Format–Any valid value from [TextureProcessorOutputFormat](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessorOutputFormat). Textures are either unchanged, converted to the Color format, or Compressed using the specified Compression algorithm.
    *X Axis Rotation–Number, in degrees of rotation. The default value is 0.
    * Y Axis Rotation–Number, in degrees of rotation. The default value is 0.
    * Z Axis Rotation–Number, in degrees of rotation. The default value is 0. +| Sprite Font Texture|[FontTextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.FontTextureProcessor)|[TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|[SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent)|A parameterized Content Processor that outputs a sprite font texture as a [SpriteFontContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.SpriteFontContent) object.
    Available parameters:

    * First Character–Any valid character. The space character is the default value.| +| Texture|[TextureProcessor](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessor)|[TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|[TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent)|A parameterized Content Processor that outputs textures as a [TextureContent Class](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.TextureContent) object.
    Available parameters:

    *Color Key Color–Any valid [Color](xref:Microsoft.Xna.Framework.Color). [Magenta](xref:Microsoft.Xna.Framework.Color) is the default value.
    * Color Key Enabled–A Boolean value indicating if color keying is enabled. The default value is **true**.
    *Generate Mipmaps–A Boolean value indicating if mipmaps are generated. The default value is **false**.
    * Resize to Power of Two–A Boolean value indicating if a texture is resized to the next largest power of 2. The default value is **false**.
    * Texture Format–Any valid value from [TextureProcessorOutputFormat](xref:Microsoft.Xna.Framework.Content.Pipeline.Processors.TextureProcessorOutputFormat). Textures are unchanged, converted to the **Color** format, or Compressed using the specified Compression algorithm.| + +## See Also + +- [Adding Content to a Game](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_Tips_For_Developing.md b/articles/getting_to_know/whatis/content_pipeline/CP_Tips_For_Developing.md new file mode 100644 index 0000000..06f3bec --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_Tips_For_Developing.md @@ -0,0 +1,81 @@ +--- +title: What are Tips for Developing Custom Importers and Processors? +description: The information provided here should help when you develop Content Pipeline extensions. +requireMSLicense: true +--- + +## Importing Basic Graphics Objects + +The following information should help you import basic graphics objects. + +- Make your coordinate system right-handed. + + From the standpoint of the observer, the positive x-axis points to the right, the positive y-axis points up, and the positive z-axis points toward you (out from the screen). + +- Create triangles that have a clockwise winding order. + + The default culling mode removes triangles that have a counterclockwise winding order. + +- Call [MeshHelper.SwapWindingOrder](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshHelper#Microsoft_Xna_Framework_Content_Pipeline_Graphics_MeshHelper_SwapWindingOrder_Microsoft_Xna_Framework_Content_Pipeline_Graphics_MeshContent_) to change the winding order of a triangle. + +- Set the scale for graphical objects to 1 unit = 1 meter. + +- Call [MeshHelper.TransformScene](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshHelper#Microsoft_Xna_Framework_Content_Pipeline_Graphics_MeshHelper_TransformScene_Microsoft_Xna_Framework_Content_Pipeline_Graphics_NodeContent_Microsoft_Xna_Framework_Matrix_) to change the scale of an object. + +## Taking Advantage of Content Pipeline Mesh Classes + +There are several properties and classes that are particularly useful when using [NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent) objects to represent a 3D scene or mesh. + +- The [NodeContent.Children](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent#Microsoft_Xna_Framework_Content_Pipeline_Graphics_NodeContent_Children) property represents hierarchical information. + +- The [NodeContent.Transform](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent#Microsoft_Xna_Framework_Content_Pipeline_Graphics_NodeContent_Transform) property contains the local transform of the 3D object. + +- The [Pipeline.Graphics.MeshContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshContent) class (a subclass of [Pipeline.Graphics.NodeContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.NodeContent)) is used to represent meshes. + +The Content Pipeline provides two classes that make it easier to create and work with [Pipeline.Graphics.MeshContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshContent) objects. + +- The [Pipeline.Graphics.MeshBuilder](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshBuilder) class creates new [Pipeline.Graphics.MeshContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshContent) objects, when necessary. + +- The [Pipeline.Graphics.MeshHelper](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshHelper) class implements useful operations on existing [Pipeline.Graphics.MeshContent](xref:Microsoft.Xna.Framework.Content.Pipeline.Graphics.MeshContent) objects. + +## Debugging Custom Importers and Processors + +In a manner similar to projects that create a DLL, Content Pipeline extension projects cannot be directly run or debugged. After completing a few simple steps, however, you can debug any custom importer and processor used by your game. The following procedure details these steps. + +> [!TIP] +> The Start External program control (located on the Debug page of a project's property pages) is unavailable in the Microsoft Visual Studio development environment. + +### To debug a custom importer or processor + +1. Load an existing MonoGame Content Pipeline extension project (later referred to as `ProjCP`) containing the custom importers or processors to be debugged. + +2. Create a separate test game project (later referred to as `ProjG`). + +3. In the **References** node of `ProjG`'s nested content project, add a project-to-project reference to `ProjCP`. + +4. Add one or two appropriate items of test content to `ProjG`, and ensure they are set to use the importer or processor (in `ProjCP`) you wish to debug. + +5. Open the property pages for `ProjCP`. + +6. Click the **Debug** tab, and then select **Start external program**. + +7. Enter the path to the local version of MSBuild.exe. + + For example, `C:\WINDOWS\Microsoft.NET\Framework\v3.5\msbuild.exe` on Windows. + +8. For the **Command line arguments** control, enter the path to `ProjG`'s nested content project. + + If this path contains spaces, quote the entire path. + +9. Set any required breakpoints in the importer or processor code in `ProjCP`. + +10. Build and debug `ProjCP`. + +Debugging `ProjCP` causes MSBuild to compile your test content while running under the debugger. This enables you to hit your breakpoints in `ProjCP` and to step through your code. + +## See Also + +- [What Is Content?](CP_Overview.md) +- [What is the Content Pipeline?](CP_Architecture.md) +- [Extending a Standard Content Processor](../../howto/Content_Pipeline/HowTo_Extend_Processor.md) +- [Adding New Content Types](CP_Content_Advanced.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/CP_XML_Elements.md b/articles/getting_to_know/whatis/content_pipeline/CP_XML_Elements.md new file mode 100644 index 0000000..9bf6ff7 --- /dev/null +++ b/articles/getting_to_know/whatis/content_pipeline/CP_XML_Elements.md @@ -0,0 +1,89 @@ +--- +title: What are the XML Elements for XMLImporter? +description: The base elements that are recognized by XmlImporter Class. +requireMSLicense: true +--- + +## XML Elements + +The following base elements are recognized by [XmlImporter Class](xref:Microsoft.Xna.Framework.Content.Pipeline.XmlImporter): + +|Element|Parent|Children|Description| +|-|-|-|-| +|``|—|``|Top-level tag for XNA Content.| +|``|``|``|Marks the asset. The _Type_ attribute specifies the corresponding namespace and class of the matching data type.| +|``|``|—|When the asset contains multiple objects (as in an array), marks a single object within the group. The child elements correspond to the properties of the data type's class definition.| + +## Examples + +## Example 1: Single Object + +This example demonstrates an XML file that defines an asset that consists of a single item (not an array). + +Assume that the XML file is to define a single object of data for the class that is defined as: + +```csharp +namespace XMLTest +{ + class MyTest + { + public int elf; + public string hello; + } +} +``` + +The XML file that specifies the data that the Content Loader will read into the object would appear as: + +```xml + + + + 23 + Hello World + + +``` + +## Example 2: Multiple Objects + +This example demonstrates an XML file that defines an asset that is an array of objects. + +Assume that the XML file is to define an array of data for the class that is defined as: + +```csharp +namespace MyDataTypes +{ + public class CatData + { + public string Name; + public float Weight; + public int Lives; + } +} +``` + +The XML file that specifies the data that the Content Loader will read into the object array would appear as: + +```xml + + + + + Rhys + 17 + 9 + + + Boo + 11 + 5 + + + +``` + +## See Also + +- [Using an XML File to Specify Content](../../howto/Content_Pipeline/HowTo_UseCustomXML.md) +- [Adding Content to a Game](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) diff --git a/articles/getting_to_know/whatis/content_pipeline/index.md b/articles/getting_to_know/whatis/content_pipeline/index.md index ee4ddfe..3094a0b 100644 --- a/articles/getting_to_know/whatis/content_pipeline/index.md +++ b/articles/getting_to_know/whatis/content_pipeline/index.md @@ -1,7 +1,53 @@ --- title: What is the Content pipeline? -description: The topics in this section describe how to add and load content such as textures, meshes, sounds, and data in your game. +description: The topics in this section describe how the content pipeline works and thr requirements for extending it to meet your games needs. requireMSLicense: true --- -## Coming soon \ No newline at end of file +## In This Section + +* [What Is Content?](CP_Overview.md) + + Describes the purpose of the MonoGame Content Pipeline and how it helps you add art and data assets to your game. + +* [Loading Content](../../howto/Content_Pipeline/HowTo_GameContent_Add.md) + + Demonstrates how to load content such as models, textures, sounds, and effects. + +* [What is the Content Pipeline Architecture?](CP_Architecture.md) + + The Content Pipeline is designed to be extensible, so that it can easily support new input file formats and new types of conversion. + +* [Standard Content Importers and Content Processors](CP_StdImpsProcs.md) + + Describes the standard Content Pipeline Content Importers and Content Processors of MonoGame that support various common art asset file formats. + +* [What is a Custom Importer](CP_AddCustomProcImp.md) + + MonoGame provides standard importers and processors for a number of common file formats used to store such basic game assets as models, materials effects, sprites, textures, and so on. For a list of file formats supported by these standard importers and processors. + +* [Parameterized Content Processors](CP_StdParamProcs.md) + + Describes how parameterized Content Processors work in MonoGame. Many of the standard Content Pipeline Content Processors shipped with MonoGame support parameter usage. + +* [What are Tips for Developing Custom Importers and Processors?](CP_Tips_For_Developing.md) + + The information provided here should help when you develop Content Pipeline extensions. + +## References + +* [What is MonoGame Content Pipeline Class Library?](CP_Class_Library.md) + + An overview of the MonoGame Content Pipeline Class Library reference, containing all the API calls available to the MonoGame Framework Content Framework. + +* [What is the Content Pipeline Document Object Model?](CP_DOM.md) + + The MonoGame Content Document Object Model (DOM) represents the set of built-in classes that can be consumed by standard content processors. + +* [What is Sprite Font XML Schema Reference?](CP_SpriteFontSchema.md) + + Describes the valid tags and values for Sprite-Font (.spritefont) XML files used by the Content Pipeline to create SpriteFont textures. + +* [What are the XML Elements for XMLImporter?](CP_XML_Elements.md) + + The base elements that are recognized by XmlImporter Class. diff --git a/articles/getting_to_know/whatis/content_pipeline/toc.yml b/articles/getting_to_know/whatis/content_pipeline/toc.yml index bd892b8..050480d 100644 --- a/articles/getting_to_know/whatis/content_pipeline/toc.yml +++ b/articles/getting_to_know/whatis/content_pipeline/toc.yml @@ -1,2 +1,12 @@ - name: <- Back - href: ../index.md \ No newline at end of file + href: ../index.md +- name: What is Content? + href: CP_Overview.md +- name: Loading Content + href: ../../howto/Content_Pipeline/HowTo_GameContent_Add.md +- name: Content Pipeline Architecture + href: CP_Architecture.md +- name: MonoGame Content Pipeline Class Library + href: CP_Class_Library.md +- name: Content Pipeline Document Object Model + href: CP_DOM.md \ No newline at end of file diff --git a/articles/getting_to_know/whatis/images/CP_CustomData.png b/articles/getting_to_know/whatis/images/CP_CustomData.png new file mode 100644 index 0000000..13156b7 Binary files /dev/null and b/articles/getting_to_know/whatis/images/CP_CustomData.png differ diff --git a/articles/getting_to_know/whatis/images/CP_CustomImporter.png b/articles/getting_to_know/whatis/images/CP_CustomImporter.png new file mode 100644 index 0000000..1374a6d Binary files /dev/null and b/articles/getting_to_know/whatis/images/CP_CustomImporter.png differ diff --git a/articles/getting_to_know/whatis/images/ContentPipelineTypes_small.png b/articles/getting_to_know/whatis/images/ContentPipelineTypes_small.png new file mode 100644 index 0000000..2f35106 Binary files /dev/null and b/articles/getting_to_know/whatis/images/ContentPipelineTypes_small.png differ