Introduction

Tomahawk uses materials for rendering the objects in the game. A material is composed of an effect shader and several textures, and it defines how an object will look like in the game. For convenience, materials are grouped in material collections so they can be easily configured.

Editing a material collection by hand would be a hard task because there are too many parameters to configure and you usually need to see in real time the resulting material. For this reason, Tomahawk uses an external program (a material editor) for creating the material collection and uses an importer / processor pair to convert the material collection to a resource usable by the game engine. Right now, there is an importer for NVIDIA's FX Composer.

The workflow will usually go like this. First, you would create a new material collection in FX Composer. You would write the shaders used by your materials, add the required textures and configure their parameters. The great thing about FX Composer is that you can see in real time the result materials in the preview window, and your material will look like this in the game.

Once you are satisfied with the materials, you add the FX Composer's project to the content project of your game and configure the content importer and processor to create the resources required by the game engine. This way, when you click the build button in Visual Studio, the materials in your game will be updated from the material collection in the FX Composer project. If you add new materials or tweak existing ones, the changes will be applied to the materials in the game the next time you compile.

Finally, you have to assign the materials in your collection to the objects in the game. This is done using archetypes. For each type of object in your game, Tomahawk uses an XML file that works as a template for creating this object in game. This template defines, among other things, the material that will be used for rendering the object. So, for applying a material to an object you just have to edit that object's archetype and assign it the new material.

To sum up, the workflow for using materials in Tomahawk is:

• Create a material collection in FX Composer
• Add the material collection to the Content Project
• Apply the materials to the game objects using archetypes

Introduction to SAS

And now for the hard part. Tomahawk is designed so you don't have to write any C# code for using your materials in the game. All the information needed for rendering the material (including the textures and passes to use) is included in the effect file (.fx). For this purpose, a script must be included in the effect file. When the effect is loaded, the engine will parse this script and will execute it when rendering the material. Also, most effects need some additional information about the object to render and this information must be passed from the game engine to the shader before rendering. A common example is the object's position and orientation, but some effects might need other ingame properties like the elapsed time or the light's position. The shader defines what information it needs from the engine by using semantics. This topic will be covered in a later section of this manual. For now, all you need to know is that a semantic is a keyword that tells the engine what value is needed for each variable in the shader.

Sending all the required information from the engine to the shaders can be done in many different ways. Tomahawk uses the SAS standard for that purpose. This standard is used by many material editors (such as FX Composer) to define the whole rendering setup for an object. This means that the materials will look (exactly) the same in the game and in the editor, and that no additional code is needed in the game for using a specific material. For detailed information on how to program using SAS, read NVIDIA's Documentation. The tutorials in this manual are a good starting point for learning how to use SAS in your material effects, but for in-depth information you should read the documentation.

Creating a material collection in FX Composer

The first thing that you have to do is to create the material collections that your game will use. You can create as many material collections as you want, but keep in mind that all the materials in a collection will be loaded when the collection is loaded, so you should group the materials that will be used together (for example, all the materials in a level). For creating a material collection, you will need FX Composer, that can be downloaded from here.

1. Open FX Composer and create a new project. The project must be located in a directory inside your project's content source directory. For example, if your content project is in C:\MyGame\Content, the FX Composer project must be inside this folder (for example: C:\MyGame\Content\Level1\Materials). All the resources used by the material collection (such as effect files and textures) must be inside the content project folder too.
2. Add new materials to the material collection. For this you can directly use FX Composer if you want to write the effect files yourself or you can use Mental Mill (which is installed with FX Composer) if you want to use a visual material editor. In any case, you should read FX Composer documentation to learn how to use it for creating materials. Later in this document you can find a small tutorial for creating a simple material in FX Composer.
3. Add the SAS semantics and annotations that are needed for your effects to work. In the tutorial section you can find an example of this.
4. Tweak your material parameters in FX Composer until you get the desired results. You can use the preview window to see how your materials will look in game.
5. Once you are satisfied with the materials, save the project and open Visual Studio for adding the material collection to your game.

Adding the material collection to the Content Project in Visual Studio

When you have your material collection ready, you have to add it to your content project so it gets exported with the rest of the resources of your game. 

1. Open your game solution in Visual Studio and open your Content Project
2. Ensure that your content project has a reference to Tomahawk.Processors. This DLL is needed for importing the FX Composer project into a material collection in Tomahawk.



3. Add your materials source files to the content project. You must include all the texture files (*.png, *.jpg, ...), the effect files (*.fx) and, most important, the FX Composer project (*.dae). This file contains the description of all the materials in your collection. Ensure that you have added all the required source files, as the collection importer will not add any file that is missing.
4. Configure the content importers and processors for your source files. For the texture and effect files, Visual Studio should autodetect the importers to use. And for the DAE file, if you added the reference to Tomahawk.Processors, Visual Studio should autodetect the importer as well. Just to be sure, check that the DAE file has the following properties set.



Compile the content project and check that in the output folder is the material collection file. For example, a file named Generics.dae should create a file named Generics.xnb. If you can't find it, there has been a problem exporting the collection and you should check the steps above.

5. Once you have succesfully exported the collection, you can use the materials in the objects in the game.

Using materials from the collection in the game

There are two kinds of materials in a collection: object materials and post processing effects, depending on whether they are used per object or applied to the whole scene as a postprocessing effect.

Object materials

You can assign materials to your game objects using archetypes (XML files). You can find detailed information on how to use archetypes in Tomahawk here. For adding materials to an object's archetype, you must do the following. Let's assume that you have the following archetype:

<?xml version="1.0" encoding="utf-8" ?>
<!-- This file describes an actor that has a component             -->
<TeapotActor>
<Components>
    <XMaterialMeshComponent type="Tomahawk.Runtime.Logic.XMaterialMeshComponent">
      <MeshName>Examples.Particles.Content\teapot</MeshName>
    </XMaterialMeshComponent>
  </Components>
</TeapotActor>

In the XMaterialMeshComponent section of the archetype you can specify the materials that will be used for rendering this object. For each mesh part in the mesh resource you can specify a material. If you don't specify a material for one part, then the default material will be used for that part. Material are assigned to mesh parts using the following line:

<MaterialDefinition meshpart=PART_NAME material=MATERIAL_ID/>

PART_NAME is the name of the mesh part, as defined in the original mesh file (for example, in an FBX file).

MATERIAL_ID is the ID of the material. This ID has the form MATERIAL_NAME@COLLECTION_FILE, where MATERIAL_NAME is the name of the material (defined in FX Composer) and COLLECTION_FILE is the material collection resource file generated from the DAE file.

In the example, if the object has two mesh parts (named Teapot01 and Teapot02) and we have a material collection file named Tomahawk.Content\Materials\generics with two materials (material01 and material02), then we would add the following lines to the object's archetype:

<Components>
  <XMaterialMeshComponent type="Tomahawk.Runtime.Logic.XMaterialMeshComponent">
    <MeshName>Examples.Particles.Content\teapot</MeshName>
    <Materials>
       <MaterialDefinition meshpart="Teapot01" material="material01@Tomahawk.Content\Materials\generics"/> 
       <MaterialDefinition meshpart="Teapot02" material="material02@Tomahawk.Content\Materials\generics"/>
    </Materials>
  </XMaterialMeshComponent>
</Components>

If everything went right, when you create an object in the game using this archetype, the object will be rendered using materials 01 and 02.

Scene Post-Processing Effects

In the configuration file of the project you can specify the postprocessing effect that will be used for rendering the game. You just have to add the following line to the XEngineConfiguration archetype:

  <SceneShader>MATERIAL_ID</SceneShader>

MATERIAL_ID is the ID of the postprocessing material, and has the same form as a normal object material: MATERIAL_NAME@COLLECTION_FILE. In some cases you may want to dinamically change the shader used by the game. You can do this by setting the SceneShader property of the RenderManager in your game's code.

Advanced topics

Rendering Groups

(to be added soon)

Appendix

SAS Parameters

In the following table you can find the SAS parameters that are currently implemented in Tomahawk

SAS Script Commands

In the following tables you can find the SAS script commands that can be used in Tomahawk for controlling the rendering of the game. A script is an annotation named "Script" that is added to any technique or pass of the shader, or to the STANDARDGLOBAL variable. The technique script defines what the engine has to do when using that technique, while the pass script tells what to do when using a pass inside a technique. The STANDARDGLOBAL script defines what techniques must be used for each render group.

Shader script

This script is associated to the STANDARDGLOBAL variable of the shader and defines what kind of shader it is (object or scene shader) and the techniques to use for each render group.

float Script : STANDARDSGLOBAL <
    string UIWidget = "none";
    string ScriptClass = "object";
    string ScriptOrder = "standard";
    string ScriptOutput = "color";
    string Script = "Technique=Color?MainColor;"
		"Technique=Depth?MainDepth;";
> = 0.8;

Links

• FX Composer
• SAS Documentation