Custom Materials

If for some reason you cannot find the material to inherit or you need a special post-process, there is a way of creating a brand new material. This way is not recommended, as even slight changes in the source code can influence your material and it would not work correctly.

The algorithm of a custom material creation is the following:

1. Create a material library - a .mat file in the target directory (all of the Unigine libraries are located in the data/core/materials/default directory).
2. Create a base material declaration in the created material library.
3. Specify a set of shaders - either combine existing shaders or write your own ones.
4. Depending on the set of shaders, add required textures, parameters, and states to the declaration.
5. Check, if the new material is loaded and rendered correctly.

As an example, lets examine the custom mesh_noise material, written as a sample for shaders (samples/shaders/mesh_noise_00.cpp). This material is changed dynamically according to the noise.

A material file can be found in the samples/shaders/materials/mesh_noise.mat directory. It contains common for all of the materials states, passes and textures. But there are a custom vertex shader and two custom parameters, noise_transform and vertex_noise, which are created specially for this material.

Lets examine a structure of a material file:

1. XML file and material library declaration.

   Source code (XML)

   <?xml version="1.0" encoding="utf-8"?>
   <materials version="1.00" editable="0">
    ...
   </materials>

   The versionof the XML file is1.0, the encoding is an UTF-8.

   A versionof the.mat file is 1.00. The editableflag is set to0, which indicates that the library is not editable.

2. Material declaration.

   Source code (XML)

   <material name="mesh_noise" editable="0">
    ...
   </material>

   A nameof the new material ismesh_noise. The editableflag is set to0, which indicates that the base material is not editable.

3. Specifying material states to be displayed in Materials Editor.

   Source code (XML)

   <state name="deferred" type="switch" items="none,default">1</state>
   <state name="ambient" type="switch" items="none,opacity,transparent">1</state>
   <state name="light_prob" type="switch" items="none,default">0</state>
   <state name="light_spot" type="switch" items="none,default">1</state>
   <state name="light_omni" type="switch" items="none,default">1</state>
   <state name="light_proj" type="switch" items="none,default">1</state>
   <state name="light_world" type="switch" items="none,default">1</state>

   Seven states are used for this material: deferred,ambient,light_prob,light_spot,light_omni,light_projandlight_world. The set values of the states are responsible for theshaderto be used.

   All of the passes have the same attributes: name(their names),type(all of the passes are of theswitchtype), items (none and default for all of the passes except for the ambientpass; it hasnone, opacity and transparent items). The default values are specified in the body of the element, so all the passes are enabled except for the light_probpass.

4. Specifying wireframe shaders to be used.

   Wireframe shaders are required for the wireframe mode, to display the mesh grid.

   Source code (XML)

   <shader pass="wireframe" object="mesh"
   	defines="BASE_WIREFRAME"
   	vertex="shaders/mesh_noise/vertex.shader"
   	geometry="core/shaders/default/common/geometry_base_wireframe.shader"
   	fragment="core/shaders/default/common/fragment_base_wireframe.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,wireframe
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_WIREFRAME
   • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages
   • geometry - a path to the built-in geometry shader,core/shaders/default/common/geometry_base_wireframe.shader
   • fragment - a path to the built-in fragment shader,core/shaders/default/common/fragment_base_wireframe.shader
5. Specifying deferred shaders to be used.
   Source code (XML)

   <shader pass="deferred" object="mesh"
   	defines="BASE_DEFERRED"
   	deferred="1"
   	vertex="shaders/mesh_noise/vertex.shader"
   	fragment="core/shaders/default/mesh/fragment_base_deferred.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,deferred
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_DEFERRED
   • deferred - a flag, indicating when the deferred pass will be applied. Set to 1, so according to the deferredstate, will be applied if state set asdefault
   • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages
   • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_deferred.shader
6. Specifying ambient shaders to be used.
   Source code (XML)

   <shader pass="ambient" object="mesh"
   	defines="BASE_AMBIENT,AMBIENT"
   	ambient_defines="0,OPACITY,TRANSPARENT"
   	vertex="shaders/mesh_noise/vertex.shader"
   	fragment="core/shaders/default/mesh/fragment_base_ambient.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,ambient
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_AMBIENT, AMBIENT
   • ambient_defines - defines of the ambient pass items. The define will be used in accordance with the setambientstate value,0 - none, OPACITY - opacity, TRANSPARENT - transparent
   • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages
   • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_ambient.shader
7. Specifying prob light shaders to be used.
   Source code (XML)

   <shader pass="light_prob" object="mesh"
   	defines="BASE_LIGHT_PROB,PROB"
   	light_prob="1"
   	vertex="shaders/mesh_noise/vertex.shader"
   	fragment="core/shaders/default/mesh/fragment_base_light_prob.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,light_prob
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_LIGHT_PROB, PROB
   • light_prob - a flag, indicating when the prob light pass will be applied. Set to 1, so according to the light_probstate, the pass will be applied if state set asdefault
   • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages
   • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_light_prob.shader
8. Specifying spot light shaders to be used.
   Source code (XML)

   <shader pass="light_spot" object="mesh"
   	defines="BASE_LIGHT_SPOT,SPOT"
   	light_spot="1"
   	vertex="shaders/mesh_noise/vertex.shader"
   	fragment="core/shaders/default/mesh/fragment_base_light_spot.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,light_spot
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_LIGHT_SPOT, SPOT
   • light_spot - a flag, indicating when the spot light pass will be applied. Set to 1, so according to the light_spotstate, the pass will be applied if state set asdefault
   • vertex - a path to the custom vertex shader,shaders/mesh_noise/vertex.shader
   • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_light_spot.shader
9. Specifying omni light shaders to be used.
   Source code (XML)

   <shader pass="light_omni" object="mesh"
   	defines="BASE_LIGHT_OMNI,OMNI"
   	receive_shadow_defines=",SHADOW"
   	light_omni_defines="0,PHONG_RIM"
   	vertex="shaders/mesh_noise/vertex.shader"
   	fragment="core/shaders/default/mesh/fragment_base_light_omni.shader"/>

   A shaderelement consists of the following attributes:

   • pass - a name of the described pass,light_omni
   • object - an object to which a shader will be applied,mesh
   • defines - shader definitions,BASE_LIGHT_OMNI, OMNI
   • receive_shadow_defines - defines of theReceive shadow option. If enabled, the SHADOW define will be passed
   • light_omni_defines - defines of the omni light pass. If thelight_omnistate is set asdefault, a PHONG_RIM define will be passed; if it is set to none, 0 will be passed
   • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages.
   • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_light_omni.shader
10. Specifying projected light shaders to be used.
    Source code (XML)

    <shader pass="light_proj" object="mesh"
    	defines="BASE_LIGHT_PROJ,PROJ"
    	receive_shadow_defines=",SHADOW"
    	light_proj_defines="0,PHONG_RIM"
    	vertex="shaders/mesh_noise/vertex.shader"
    	fragment="core/shaders/default/mesh/fragment_base_light_proj.shader"/>

    A shaderelement consists of the following attributes:

    • pass - a name of the described pass,light_proj
    • object - an object to which a shader will be applied,mesh
    • defines - shader definitions,BASE_LIGHT_PROJ, PROJ
    • receive_shadow_defines - defines of theReceive shadow option. If enabled, the SHADOW define will be passed
    • light_proj_defines - defines of the projected light pass. If thelight_proj state is set as default, a PHONG_RIM define will be passed; if it is set to none, 0 will be passed
    • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages.
    • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_light_proj.shader
11. Specifying world light shaders to be used.
    Source code (XML)

    <shader pass="light_world" object="mesh"
    	defines="BASE_LIGHT_WORLD,WORLD"
    	receive_world_shadow_defines=",SHADOW"
    	light_world_defines="0,PHONG_RIM"
    	vertex="shaders/mesh_noise/vertex.shader"
    	fragment="core/shaders/default/mesh/fragment_base_light_world.shader"/>

    A shaderelement consists of the following attributes:

    • pass - a name of the described pass,light_world
    • object - an object to which a shader will be applied,mesh
    • defines - shader definitions,BASE_LIGHT_WORLD, WORLD
    • receive_shadow_defines - defines of theReceive shadow option. If enabled, the SHADOW define will be passed
    • light_world_defines - defines of the world light pass. If thelight_world state is set as default, a PHONG_RIM define will be passed; if it is set to none, 0 will be passed
    • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages.
    • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_light_world.shader
12. Specifying shadow shaders to be used.

    A separate shadow shaders are required to render correct shadows.

    Source code (XML)

    <shader pass="shadow" object="mesh"
    	defines="BASE_SHADOW"
    	vertex="shaders/mesh_noise/vertex.shader"
    	fragment="core/shaders/default/mesh/fragment_base_shadow.shader"/>

    A shaderelement consists of the following attributes:

    • pass - a name of the described pass,shadow
    • object - an object to which a shader will be applied,mesh
    • defines - shader definitions,BASE_SHADOW
    • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages.
    • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_shadow.shader
13. Specifying translucency shaders to be used.
    Source code (XML)

    <shader pass="translucent" object="mesh"
    	defines="BASE_SHADOW,TRANSLUCENT"
    	vertex="shaders/mesh_noise/vertex.shader"
    	fragment="core/shaders/default/mesh/fragment_base_shadow.shader"/>

    A shaderelement consists of the following attributes:

    • pass - a name of the described pass,translucent
    • object - an object to which a shader will be applied,mesh
    • defines - shader definitions,BASE_SHADOW, TRANSLUCENT
    • vertex - a path to the custom vertex shader,samples/shaders/shaders/mesh_noise/vertex.shader. This shader is written for OpenGL and DirectX APIs by using GLSL and HLSL shading languages.
    • fragment - a path to the built-in fragment shader,core/shaders/default/mesh/fragment_base_shadow.shader

14. Set bindings.

    Source code (XML)

    <bind object="mesh_cluster" to="mesh"/>
    <bind object="mesh_clutter" to="mesh"/>
    <bind object="mesh_dynamic" to="mesh"/>

    Cluster, clutter and dynamic mesh will act like a mesh.

15. Specify textures to be used for the material.

    Source code (XML)

    <texture name="diffuse" anisotropy="1">core/textures/mesh_base_diffuse.dds</texture>
    <texture name="normal" pass="deferred,ambient,light_prob,light_spot,light_omni,light_proj,light_world,translucent" format="signed" anisotropy="1">core/textures/mesh_base_normal.dds</texture>
    <texture name="specular" pass="deferred,ambient,light_prob,light_spot,light_omni,light_proj,light_world" anisotropy="1">core/textures/mesh_base_specular.dds</texture>
    <texture name="ambient" pass="ambient" unit="12" format="srgb">core/textures/mesh_base_ambient.dds</texture>
    <texture name="deferred_occlusion" pass="ambient" unit="13" type="deferred_occlusion"/>
    <texture name="deferred_light" pass="ambient" unit="15" type="deferred_light"/>
    <texture name="light_image" pass="light_omni,light_proj,light_world" unit="11" type="light_image"/>
    <texture name="light_color" pass="light_omni,light_proj,light_world" type="light_color"/>
    <texture name="light_depth" pass="light_omni,light_proj,light_world" type="light_depth"/>
    <texture name="light_noise" pass="light_omni,light_proj,light_world" type="light_noise"/>
    <texture name="light_vcube" pass="light_omni" type="light_vcube"/>

    To create a material, 11 textures were used. Four textures, nameddiffuse, normal, specular and ambient are using custom textures, written in the body of the textureelement. The other seven textures use built-in texture types. They are specified by thetypeattribute:deferred_occlusion,deferred_light,light_image,light_color,light_depth,light_noiseandlight_vcube correspondingly.

    An anisotropyflag of thediffuse texture is set to 1, so anisotropy effect for the diffuse texture is enabled.

    The passelement specifies the pass during which textures will be rendered:deferred,ambient,light_prob,light_spot,light_omni,light_proj,light_worldortranslucentdepending on the texture. For thediffuse texture, the pass is not specified, so it will be rendered during all of the passes.

    The ambient, deferred_light, deferred_occlusion and light_image textures have an unitattribute, specifying the number of a Texture Mapping Unit:12, 13, 15 and 11 correspondingly.

    The normal and ambient textures have an attribute format, specifying the format of the texture,signed and srgb correspondingly.

16. Set parameters of the material.

    Source code (XML)

    <parameter name="base_transform" type="expression" shared="1">vec4(1.0f,1.0f,0.0f,0.0f)</parameter>
    <parameter name="environment_scale" type="slider" shared="1" min="0.0" max="4.0" flags="max_expand">1.0</parameter>
    <parameter name="diffuse_color" type="color" shared="1">1.0 1.0 1.0 1.0</parameter>
    <parameter name="diffuse_scale" type="slider" min="0.0" max="4.0" flags="max_expand">1.0</parameter>
    <parameter name="specular_color" type="color" shared="1">1.0 1.0 1.0 1.0</parameter>
    <parameter name="specular_scale" type="slider" min="0.0" max="4.0" flags="max_expand">1.0</parameter>
    <parameter name="specular_power" type="slider" shared="1" min="0.0" max="2.0" flags="log10,max_expand">16.0</parameter>
    <parameter name="phong_rim_width" type="slider" min="0.0" max="1.0">0.5</parameter>
    <parameter name="phong_rim_scale" type="slider" min="0.0" max="1.0">0.0</parameter>
    <parameter name="fresnel_bias" type="slider" min="0.0" max="1.0">1.0</parameter>
    <parameter name="fresnel_power" type="slider" min="0.0" max="1.0" flags="log10,max_expand">5.0</parameter>
    <parameter name="noise_transform" type="constant" shared="1">0.0 0.0 0.0 0.0</parameter>
    <parameter name="vertex_noise" type="array" shared="1"/>

    The material has 11 built-in and 2 custom parameters. Built-in parameters: base_transform, environment_scale, diffuse_color, diffuse_scale, specular_color, specular_scale, specular_power, phong_rim_width, phong_rim_scale, fresnel_bias and fresnel_power. Custom parameters: noise_transform and vertex_noise.

    The vertex_noise is an array of 66 variables. The noise_transform parameter changes the coordinates of the mesh vertices each frame in accordance with the noise, created by the vertex_noise parameter.

    The parameterelements consist of the following attributes:

    • name- names of the parameters
    • type- types of the parameters,expression, slider, color, constant and array
    • shared- a flag, indicating
    • minandmax- minimum and maximum possible values
    • flags- additional parameters,max_expand, log10