ShaderFX / Stingray PBS material to Simplygon material ​

This section goes through how to set up a Stingray PBS material, how to export and import a material to and from Simplygon using Simplygon shading networks. We recommend reading Shading network concepts before proceeding.

First, make sure the ShaderFX plug-in (.mll) is loaded in the plug-in manager (Windows -> Settings / Preferences -> Plug-in Manager) as in figure 1.

Figure 1: ShaderFX plug-in loaded in the plug-in manager.

Let’s create a cube as in figure 2. This cube will be the target for our soon to be created Stingray PBS material.

Figure 2: A cube.

To create a new Stingray PBS material, go to Hypershade (Windows -> Rendering Editors -> Hypershade) and click the Stingray PBS shader (figure 3).

Figure 3: How to create a Stingray PBS material in Hypershade.

In the right-most panel in figure 3 there's a material name, for this tutorial we'll set it to MyMaterial. The Property Editor should now be listing various material properties for the standard preset (figure 4).

Figure 4: Stingray PBS material with properties.

It is now time to assign the material to our asset; select the asset, go to Hypershade, then click and hold the right mouse button on the recently created shader followed by releasing the button when hovering assign to selection.

Another way to do this is to simply drag the material from Hypershade (using the middle mouse button) and drop it onto the asset.

If we close Hypershade and bring forth the attribute editor (ctrl + A), then the asset should render with the new material. We have already prepared some textures for this specific material to make it somewhat more describing (figure 5).

Figure 5: Cube with Stingray PBS material successfully applied.

That is it, we now have an asset with a Stingray PBS material attached to it!

Scripting ​

To translate a Stingray PBS material to a Simplygon material you might want to extract certain properties from your shader, for example a texture. The color texture slot that is marked in figure 6 maps to the material's TEX_color_map.

Figure 6: color texture slot.

If we open up ShaderFX (button at the top of the material) we can also see that there is a switch node that switches between base_color and TEX_color_map based on the state of use_color_map (figure 7).

Figure 7: color switch.

It is up to us if we want to read these flags and generate the appropriate material for all cases, in this tutorial we will keep it simple and focus on textures. The complete script will be referenced at the end of this tutorial.

Export ​

The first thing we need to do is to create a (shading) texture node using the SimplygonShadingNetwork-command along with the cn-flag (CreateNode), the name of the material, the type of the shading node as well as the name of the texture slot (from where to read the texture path).

SimplygonShadingNetwork
    -cn $materialName TextureNode TEX_color_map;

To connect the shading network exit node to a Simplygon material channel (in this case to a channel named color), we add another row to our script.

SimplygonShadingNetwork
    -cn $materialName TextureNode TEX_color_map
    -sce $materialName color TEX_color_map;

Commands in Maya are not state based and does not share any information, so to be able to pass the shading network templates from SimplygonShadingNetwork to Simplygon we'll store the information to disk (using the exf-flag). Let’s add another flag to the SimplygonShadingNetwork-command.

SimplygonShadingNetwork
    -cn $materialName TextureNode TEX_color_map
    -sce $materialName color TEX_color_map
    -exf $materialName color ($xmlExportPath + $materialName + "_color.xml");

Now, after running this script there should be a xml file in the specified output folder containing the shading network template for the specific material channel. We'll now use the generated template as input when calling the Simplygon-command.

First we need the material input arguments for the Simplygon-command, which in this case is the target material name, the material channel of where to store the material data, as well as the path to the xml we exported earlier. We import the xml using Import Xml File (ixf).

string $arguments = " -ixf \"" + $materialName + "\" color \"" + ($xmlExportPath + $materialName + "_color.xml\"");

When calling the Simplygon-command we can specify some optional parameters; in this case we need:
dgm to not generate standard Phong material when importing LOD) and tod to specify a texture output directory where the resulting textures shall end up after LOD import. Finally we add the required flag, add shader material (asm) followed by material name and the previous xml import path. Remember to select the asset before running the Simplygon-command , otherwise the command will be ignored.

string $processedMeshes[] = eval("Simplygon -sf $pipelineFilePath -dgm -tod $textureOutputDirectory -asm $materialName " + $arguments);

Let us add the normal texture to the normal channel, this should be fairly easy from what we have learned. We add similar rows for normals as for the color texture.

SimplygonShadingNetwork
    -cn $materialName TextureNode TEX_color_map
    -cn $materialName TextureNode TEX_normal_map
    -sce $materialName color TEX_color_map
    -sce $materialName normal TEX_normal_map
    -exf $materialName color ($xmlExportPath + $materialName + "_color.xml")
    -exf $materialName normal ($xmlExportPath + $materialName + "_normal.xml");

string $arguments =
" -ixf \"" + $materialName + "\" color \"" + ($xmlExportPath + $materialName + "_color.xml\"") +
" -ixf \"" + $materialName + "\" normal \"" + ($xmlExportPath + $materialName + "_normal_.xml\"");

string $processedMeshes[] = eval("Simplygon -sf $pipelineFilePath -dgm -tod $textureOutputDirectory -asm $materialName " + $arguments);

This is a short example of how to use shading networks to translate a Stingray PBS shader. Please take a look at the tables above including shading nodes, commands and flags to see what is available. There are also a couple of examples at the end of this document which is focusing more on shading nodes and hierarchy.

This is the end of the export part and how to get the asset to Simplygon. What happens next is more dependent on the settings that is used for processing and what kind of LODs that come back.

Import ​

If we continue where we left off at the export step the return value of the Simplygon-command will contain the names of the processed meshes.

string $processedMeshes[] = eval("Simplygon -sf $pipelineFilePath -dgm -tod $textureOutputDirectory -asm $materialName " + $arguments);

The Simplygon Maya plug-in stores some material information from the last run to give the user the possibility to manually setup materials (via script). To access such information we will use the SimplygonQuery-command with the appropriate flags. We will start by asking the Simplygon plug-in for the material name of a mesh, available material channels as well as textures.

for($m in $processedMeshes)
{
    $m = substituteAllString($m, "|", "");
    print ("\nMesh: " + $m + "\n");
    string $material;
    $material = `SimplygonQuery -gmm $m`;
    print ("  Material: " + $material + "\n");
    $channels = `SimplygonQuery -gcm $material`;
    for($c in $channels)
    {
        print ("    Channel: " + $c + "\n");
        $filepath = `SimplygonQuery -gtc $material $c`;
        print ("      Texture: " + $filepath + "\n");
    }
}

What remains is to create a target Stingray PBS material (or any other material) and map back the information that was fetched from the SimplygonQuery-command. We've excluded the material creation part from this tutorial as there usually are many lines of code and special conditions that does not really contribute that much, see the ShaderFX / Stingray PBS example for complete import / export scripts.