This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

User Material File Format

Material File Structure

A user material is a *.mat ("User Material") text file that overrides properties of the base material.

Notice
Options, states, textures and parameters are presented in the *.mat file only if they are overridden.
The user material is adjusted in Material Editor. If required, the *.mat text file can be edited manually.

The *.mat file is created, when the user material is inherited from the base or another user material. The new material is created in the same directory as the parent one.

Notice
When inheriting from the base material, by default, the user material is created in the data folder of the project.

The *.mat file is based on the *.xml file type and shares all its methods.

A document should have the *.xml file declaration, containing its version and the type of encoding you are using. For example, to specify the 1.0 version and UTF-8 encoding, type:

XML Code
<?xml version="1.0" encoding="utf-8"?>

As well as for the base material, the *.mat file is based on 3 entities:

  • Element. A component that may contain attributes, other elements, some content etc.
  • Attribute. A component placed inside the element tag containing the specified value.
  • Value. A component specifying the value of the attribute.

The syntax is the following:

XML Code
<parent_element attribute="value">
 <child_element_1/>
 <child_element_2>content</child_element_2>
</parent_element>

All of the *.mat file elements, attributes and values are listed below.

Material Element

A <material/> element defines a user material with the given properties.

It can have the attributes listed below.

version

A version of the *.mat file.

name

The unique name of the material. For manual materials, the name is used as identifier for the material: by using it, the material's GUID is generated in run-time.

guid

The GUID of the user material. For manual materials, the name is used instead of the GUID.

parent

a GUID of a parent material.

parent_name

A name of a parent material. The attribute is used when the parent material is the manual user material.

base_material

The name of a base material. The base material will be used as the parent one if the parent material isn't loaded.

If the parent has another base material, it will be changed to the specified one.

editable

A flag, indicating if settings of the material can be changed in Material Editor.

Available values:

  • 0 - unchangeable
  • 1 - changeable (by default)

hidden

A flag, indicating if a material is displayed in the material list of Material Editor.

Available values:

  • 0 - displayed (by default)
  • 1  -  hidden

manual

A flag, indicating if a material is manual: created or edited manually, not via Materials Editor.

Notice
If the attribute isn't specified, the manual user material won't be loaded as it will be treated as the user material without a GUID.

Available values:

  • 0 - manual (by default)
  • 1  -  not manual

Usage Example

For example, the displayed unchangeable material named user_material_0 and inherited from the mesh_base_0 user material will be as follows:

Source code (XML)
<material version="2.5.0.2" name="user_material_0" parent="3e7f5c9535777e15966cb5f915d25b62620b2bef" base_material="mesh_base" editable="0">
...
</material>

Blend Element

A <blend/> element allows you to override a value of a parent material's blending option.

It can have the attributes listed below.

src and dest

A polygon color (source image) and a screen buffer color (destination image) multipliers.

Available values for both attributes:

  • none - blending is not used.
  • zero - RGBA components of the source/destination image color are multiplied by zero.
  • one - RGBA components of the source/destination image color are multiplied by one.
  • src_color - RGBA components of the source/destination image color are multiplied by the mR, mG, mB, mA components (per component).
  • one_minus_src_color - RGBA components of the source/destination image color are multiplied by the 1 -  mR , 1 -  mG , 1 -  mB , 1 -  mA components (per component).
  • src_alpha - RGBA components of the source/destination image color are multiplied by the mA component.
  • one_minus_src_alpha - RGBA components of the source/destination image color are multiplied by the 1 -  mA component.
  • dest_color - RGBA components of the source/destination image color are multiplied by the bR, bG, bB, bA components (per component).
  • one_minus_dest_color - RGBA components of the source/destination image color are multiplied by the 1 -  bR , 1 -  bG , 1 -  bB , 1 -  bA components (per component).
  • dest_alpha - RGBA components of the source/destination image color are multiplied by the bA component.
  • one_minus_dest_alpha - RGBA components of the source/destination image color are multiplied by the 1 -  bA component.

    Where mR, mG, mB, mA are normalized Red, Blue, Green and Alpha material image channels;
    bR, bG, bB, bA are normalized Red, Blue, Green and Alpha background image channels.

Usage Example

For example, the user material that has the opaque areas receiving a material color and transparent areas receiving a screen buffer color will have the following element:

Source code (XML)
<blend src="one" dest="one_minus_src_alpha"/>

Material Editor

In Material Editor, the blending option value can be set in the Transparent group of the Common tab.

Options Element

An <options/> element stores the overridden value of the parent material's option.

order

A rendering order of the material. Specifies the priority of the material rendering inside the group.

Available values:

  • -8 - 8. The default value is 0. The higher the rendering order, the lower the rendering priority (the material with the -8 order will be rendered first).

offset

A polygon offset of the material. Can be useful to prevent a Z-fighting effect.

Available values:

  • 0 - 1024 (powers of 2). The default value is 0.

light_mask

A light viewport mask.

Available values:

  • Integer, representing a mask. The default value is ~0.

viewport_mask

A viewport mask.

Available values:

  • Integer, representing a mask. The default value is ~0.

transparent

A flag indicating whether the material is transparent.

Available values:

  • 0 - the material is opaque
  • 1 - the Alpha test blending preset.
  • 2 - the Alpha blend, Additive, Multiplicative or Custom blending preset.

depth_mask

A flag indicating if a depth mask is used for a material.

Available values:

  • 0 - not used
  • 1 - used (by default)

depth_pre_pass

A flag indicating if the native depth pre-pass is performed for a material.

Available values:

  • 0 - is performed
  • 1 - not performed

overlap

A flag indicating if an Overlap option is enabled for a material.

Available values:

  • 0 - disabled (by default)
  • 1 - enabled

two_sided

A flag indicating if a Two sided option is enabled for a material.

Available values:

  • 0 - disabled (by default)
  • 1 - enabled

depth_test

A flag indicating if a Depth test option is enabled for a material.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)

cast_shadow

A flag indicating if a Cast shadow option is enabled for a material.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)

cast_world_shadow

A flag indicating if a Cast world shadow option is enabled for a material.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)

receive_shadow

A flag indicating if a Receive shadow option is enabled for a material.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)

receive_world_shadow

A flag indicating if a Receive world shadow option is enabled for a material.

Available values:

  • 0 - disabled
  • 1 - enabled (by default)

Usage Example

For example, if you enable the Alpha test and Two sided options, the following will be written into the *.mat file:

Source code (XML)
<options alpha_test="1" two_sided="1"/>

Material Editor

In Material Editor, a common option value can be set on the Common tab.

State Element

A <state/> element stores the overridden value of the parent material's state (a mode of a rendering pass or a value of a rendering option).

name

Name of the state.

Usage Example

For example, if you set the Ambient occlusion state, the following string will be written into the *.mat file:

Source code (XML)
<state name="ao_map">1</state>

Texture Element

A <texture/> element stores the overriddden path to the texture of the parent material. The up-to-date set of built-in types of textures can be found in data/editor/editor_material_textures.h)

name

A texture name.

Available values:

  • diffuse - a diffuse texture, an alpha channel is used for a detail texturing modulation.
  • specular - a specular texture, an alpha channel is used for a glossiness modulation.
  • albedo - an albedo texture.
  • metalness - a metalness texture, an alpha channel is used for a roughness modulation.
  • shading - a shading texture (R - metalness, G - roughness, B - specular, A - microfiber).
  • normal - a two-component normal texture.
  • microfiber - a microfiber texture.
  • detail_diffuse - a detail diffuse texture, alpha channel is used for a detail texturing modulation.
  • detail_specular - a detail specular texture, alpha channel is used for a glossiness modulation.
  • detail_albedo - a detail albedo texture.
  • detail_metalness - a detail metalness texture, alpha channel is used for a roughness modulation.
  • detail_shading - a detail shading texture (R - metalness, G - roughness, B - specular, A - microfiber).
  • detail_normal - a detail two-component normal texture.
  • detail_mask - a detail blend mask texture.
  • ambient_occlusion - an ambient occlusion texture.
  • emission - an ambient emission texture, an alpha channel is used for glow post process modulation.
  • lightmap - a lightmap texture, the second texture channel is used.
  • parallax - a single channel parallax height map texture.
  • auxiliary - an auxiliary texture.
  • translucent - a translucency texture.
  • noise_2d - a spatial color noise texture.
  • grass_base_noise - a spatial color noise texture that uses a planar projection across whole grass.
  • grass_impostor_base_noise - a spatial color noise texture that uses a planar projection across grass impostors.
  • noise_3d - a 3D noise texture.
  • noise_3d_color_gradient - a gradient 3D texture for color modulation.
  • noise_3d_gradient - a 3D gradient texture.
  • ambient - a single channel environment modulation texture.
  • reflection - a static reflection texture.
  • particles_base_normal - particles texture.
  • attenuation - an attenuation texture.
  • volume_cloud_base_density - a volumetric clouds density texture.
  • volume_fog_base_noise - a single channel screen space noise texture.
  • water_base_normal_01 - the first group of water normal textures.
  • water_base_normal_23 - the second group of water normal textures.
  • water_base_foam - a water foam texture.
  • water_base_caps - a water caps texture.
  • caustic_texture - a water caustics texture.
  • sky_base_mask_0 - the first group of clouds mask texture.
  • sky_base_mask_1 - the second group of clouds mask texture.
  • sky_base_clouds_01 - the first group of clouds noise texture.
  • sky_base_clouds_23 - the second group of clouds noise texture.
  • sky_base_background_0 - the first sky cubemap background texture.
  • sky_base_background_1 - the second sky cubemap background texture.
  • heatlookup - the lookup texture for sensor.
  • foam - the water foam texture.
  • water_normal_detail_texture - the normal detail texture.
  • water_height_texture - the water height texture.
  • water_depth_lut - the LUT for depth.
  • shoreline_lut - the LUT for shoreline.

wrap

A texture wrapping methods.

Available values:

  • clamp - a texture is clamped along all axes
  • clamp_x - a texture is clamped along X-axis
  • clamp_y - a texture is clamped along Y-axis
  • clamp_z - a texture is clamped along Z-axis
  • border - a texture is bordered along all axes
  • border_x - a texture is bordered along X-axis
  • border_y - a texture is bordered along Y-axis
  • border_z - a texture is bordered along Z-axis
  • repeat - no wrap, a texture is tiled along all axes. This value can be used, for example, when a base material's texture is bordered, and the child material's texture shouldn't.

anisotropy

A flag, indicating if the anisotropy for the texture is enabled.

Available values:

  • 0  -  enabled (by default)
  • 1  -  disabled

filter

A type of the texture filtering.

Available values:

  • point   - point  
  • linear   - linear  
  • bilinear   - bilinear  

Usage Example

For example, if you change the path to the Albedo texture, the following will be written into the *.mat file:

Source code (XML)
<texture name="albedo" anisotropy="0">unigine_project/textures/ground_dirt_alb.dds</texture>

Parameter Element

A <parameter/> element stores the overridden value of the parent material's parameter.

name

Name of the parameter.

Usage Example

If you override the Albedo color and Metalness parameters of the material, inherited from the mesh_base, the following will be written into the *.mat file:

Source code (XML)
<parameter name="albedo_color">0.501960814 0 0 1</parameter>
<parameter name="metalness">0.76700002</parameter>
Last update: 2017-12-21
Build: ()