Tutorials

Tutorial: Simple material

In this first tutorial you will learn how to create a simple material in FX Composer and import it in a game using the Tomahawk engine. Let's suppose that you have a working sample of a Tomahawk game in the folder C:\MyGame, and that you have an archetype called teapot_actor.xml in the contents folder of your game (C:\MyGame\MyGame.Contents). If you don't know how to create a game sample in Tomahawk, please read this tutorial. 

Step 1: Creating the material

First of all, you have to create the material collection that will contain your materials. Open FX Composer and create a new project inside the contents folder of your game (C:\MyGame\MyGame.Contents\Materials\MyMaterials.fxcproj). Then, add a new effect file by right-clicking on Effects in the Asset Browser and choosing AddEffect... In the wizard dialog select HLSL FX and click next. Then select the Phong effect and check that the .fx file is created inside your game content folder (it is created in the same directory as the FX Composer project by default). Select the names for your effect and material and click finish for creating your first material!

Now you can find the effect file and the material you created in the Asset Browser. The Phong material template has created for you a base HLSL file with all the required SAS code for using it in FX Composer (and in Tomahawk). If you want to preview the material in real time, click the Sphere button in the toolbar and drag and drop your material on the sphere that you can see in the preview window.

The SAS script is very important for the material to work, so let's review a couple of important things. In your Phong.fx file you will find the following script:

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

This script MUST be in all your shaders and basically tells the engine the kind of material you are creating (in this case, an object material) and the technique to use for rendering the object. The line "Technique=Phong?Main" means that the engine will use the Main technique when rendering the Phong group. In the advanced topics of this manual you can learn how to use this part of the script for creating advanced effects, but for now, just replace it with "Technique=Color?Main;", which is the most common case.

If you look through the rest of the code in Phong.fx you will see that the shader variables have some semantics associated to them. The engine uses this semantics to know what value is needed for that variable in the game. For example, the following line:

float4x4 WorldITXf : WorldInverseTranspose < string UIWidget="None"; >;

tells Tomahawk that the variable WorldITXf will contain the WorldInverseTranspose matrix of the rendered object. You can find the whole list of SAS semantics in the SAS documentation. As an example, add a new variable to your shader that will receive the total game time.

float Time : Time < string UIWidget="None"; >;

And modify the pixel shader so it will use this variable for rendering the object.

float4 std_PS(vertexOutput IN) : COLOR {
    float3 diffContrib;
    float3 specContrib;
    float3 Ln = normalize(IN.LightVec);
    float3 Vn = normalize(IN.WorldView);
    float3 Nn = normalize(IN.WorldNormal);
	phong_shading(IN,Lamp0Color,Nn,Ln,Vn,diffContrib,specContrib);
    float3 diffuseColor = sin(Time) * tex2D(ColorSampler,IN.UV).rgb;
    float3 result = specContrib+(diffuseColor*(diffContrib+AmbiColor));
    // return as float4
    return float4(result,1);
}

If you compile the shader and click the play button in the toolbar, you will see that the object in the preview window is pulsing. The same will happen in the game with any object that uses this material.

The annotations that you can see in some of the variables of the shader are used by the FX Composer to know what properties or the shader are editable in the Properties Window. For example:

texture ColorTexture : DIFFUSE <
    string ResourceName = "default_color.dds";
    string UIName =  "Diffuse Texture";
    string ResourceType = "2D";
>;

Once your shader is compiled, you can easily modify the values of this properties by selecting your material in the asset browser and modifying the values in the property window. Use the property window to change the texture used by your material (texture1.png). You should see the resulting material in the preview window.

Another important thing in the shader file is the script code associated to the techniques and passes of the effect. This script tells the engine how to render the object. In other words, the rendering loop of the engine can be configured by these scripts (which techniques to use, in which order, ...) We will cover this topic in the next tutorial. For now, just leave the script as it is.

To end with this part of the tutorial we will create another material. You can reuse the shader file for as many materials as you want, and just change some properties for each material. As an example, you can create a new material by dragging the effect to the Materials section in the Asset Browser. Then, you can select a new texture for this material in the property window (texture2.png). Now you have two materials ready for being used in the game!

Step 2: Importing the material

Now you have to add the material collection to the content project of your game. Open the Visual Studio solution of your game and select the Content Project. Check that it have a reference to Tomahawk.Processors, as it is needed for importing the materials. This DLL can be found in the bin folder of your game.

Your FX Composer project have four important files to add to the content project: the HLSL file, the textures used by your materials (texture1.png and texture2.png) and the collection file (MyCollection.dae). All these files are in the FX Composer project folder, which is inside your content folder. The easiest way to add the files to your project is clicking Show All Files in the Solution Explorer and adding them by right clicking on them and selecting Include in Project. When you add the .dae collection file, Visual Studio will autodetect that it is a material collection file and will select the correct content importer and content processor to use when compiling the resource.

The material collection is ready to use! If you compile your content project, the imported material collection will be created in the resources folder of your game.