This page has been translated automatically.
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Migration
Migrating to UNIGINE 2.0
C++ API Migration
Migrating from UNIGINE 2.0 to UNIGINE 2.1
Внимание! Эта версия документация УСТАРЕЛА, поскольку относится к более ранней версии SDK! Пожалуйста, переключитесь на самую актуальную документацию для последней версии SDK.
Внимание! Эта версия документации описывает устаревшую версию SDK, которая больше не поддерживается! Пожалуйста, обновитесь до последней версии SDK.

Material File Format

Material File Structure

A material is a .mat ("Material") text file that contains all of the information to provide a required image. Its properties can be adjusted and assets can be set either in the text file or in Material Editor.

It 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"?/>

There are 3 basic entities of the .mat file:

  • 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.

Materials Element

A <materials/> element defines a material library, so all of the materials should be placed inside this element.

It can have the attributes listed below.

version

A version of the .mat file.

editable

A flag, indicating if all the child materials settings can be changed in Material Editor.

Available values:

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

For example, to specify the 1.00 version of the .mat file and make the materials unchangeable, type:

XML Code
<materials version="1.00" editable="0"></materials>

Material Element

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

It can have the attributes listed below.

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

name

The unique name of a material.

parent

The name of a parent material.

For example, to create the displayed unchangeable material named custom_base, type:

Source code (XML)
<material name="custom_base" editable="0"></material>

Options Element

An <options/> element allows you to set a value for a common option.

It can have the attributes listed below.

downsize

A downsized buffer for transparent materials.

Available values:

  • none - materials are rendered into a full-sized buffer
  • always_scale - materials are rendered into a downsized buffer to be rendered at the scene background
  • always_filter - materials are rendered into a downsized buffer and after being filtered are rendered at the scene background
  • forward_scale - materials are rendered into a downsized buffer based on the object geometry as a background layer for composing
  • forward_filter - materials are rendered into a downsized buffer based on the object geometry as a background layer for composing after being filtered
  • greater_scale - materials are rendered into a downsized buffer
  • greater_filter - materials are rendered into a downsized buffer after being filtered

group

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

Available values:

  • 0 - 8. The default value is 0, so the material has the highest rendering priority. The higher the rendering group, the lower the rendering priority.

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.

post_deferred

A flag indicating if a surface with this material should be rendered before the deferred pass or after it.

Available values:

  • 0 - after (by default)
  • 1 - before

post_refraction

A flag indicating if a surface with this material should be rendered before the refraction pass or after it.

Available values:

  • 0 - after (by default)
  • 1 - before

post_scattering

A flag indicating if a surface with this material should be rendered before the scattering pass or after it.

Available values:

  • 0 - after (by default)
  • 1 - before

depth_mask

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

Available values:

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

glow_mask

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

Available values:

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

parallax_mask

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

Available values:

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

alpha_test

A flag indicating if an Alpha test 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

light_blending

A flag indicating if a Light blending option is enabled for a material.

Available values:

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

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)

cast_translucent

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

Available values:

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

receive_translucent

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

Available values:

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

Usage Example

For example, to enable an Alpha test option, type:

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

Material Editor

In Material Editor, a common option value can be set in the Options section of the Common tab.

Blend Element

A <blend/> element allows you to set a blending option value.

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, if you want the opaque areas to receive a material color and transparent areas to receive a screen buffer color, type:

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

Material Editor

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

State Element

A <state/> element allows you to set a mode for rendering passes and a value for rendering options.

name

Name of the state.

type

A type of the switch between the state values.

Available values:

  • toggle - an enabling and disabling switch
  • switch - a multiple values switch

items

A set of available items for a multiple values switch.

Passes

There is a list of passes, used for Unigine built-in materials:

deferred

Specifies if the material is rendered into the deferred buffer during the deferred rendering pass.

Available values:

  • none - skip the pass
  • default - enable the pass

auxiliary

Specifies if the material is rendered into the auxiliary buffer during the auxiliary rendering pass.

Available values:

  • none - skip the pass
  • default - enable the pass

refraction

Specifies if the material is rendered into the refraction buffer during the refraction rendering pass.

Available values:

  • none - skip the pass
  • default - enable the pass

velocity

Specifies if the material is rendered into the velocity buffer during the post-process.

Available values:

  • none - skip the pass
  • default - enable the pass

ambient

Specifies if the material is rendered during the ambient light rendering pass.

Available values:

  • none - skip the pass
  • opacity - blend material diffuse color with the ambient color during the ambient pass
  • transparent - render material diffuse color during the ambient pass (a diffuse color is not modulated by an ambient color)
  • lightmap - render the light map during the ambient pass

light_omni

Specifies if the material is rendered illuminated by the omnidirectional light sources during the light and shadows rendering passes.

Available values:

  • none - skip the pass
  • phong-rim - materials are rendered with using a Phong rim shading model during the pass
  • anisotropy - materials are rendered with using an anisotropy shading model during the pass

light_proj

Specifies if the material is rendered illuminated by the projected light sources during the light and shadows rendering passes.

Available values:

  • none - skip the pass
  • phong-rim - materials are rendered with using a Phong rim shading model during the pass
  • anisotropy - materials are rendered with using an anisotropy shading model during the pass

light_world

Specifies if the material is rendered illuminated by the world light sources during the light and shadows rendering passes.

Available values:

  • none - skip the pass
  • phong-rim - materials are rendered with using a Phong rim shading model during the pass
  • anisotropy - materials are rendered with using an anisotropy shading model during the pass

Options

There are a lot of different purpose options used in Unigine built-in materials. The full list of them can be found in the core/editor/editor_materials_states.h directory.

Usage Example

For example, if you want to specify the deferred pass, enabled by default, type:

Source code (XML)
<state name="deferred" type="switch" items="none,default">1</state>
Notice
Do not forget to specify a shader for the pass.

Texture Element

A <texture/> element allows you to specify a texture to be used.

name

A texture name.

pass

A pass during which a texture will be rendered.

Available values:

  • wireframe - a wireframe pass
  • deferred - a deferred pass
  • auxiliary - an auxiliary pass
  • refraction - a refraction pass
  • velocity - a velocity pass
  • ambient - an ambient pass
  • light_prob - a prob light pass
  • light_spot - a spot light pass
  • light_omni - an omni-directional light pass
  • light_proj - a projected light pass
  • light_world - a world light pass
  • translucent - a translucent pass
  • shadow - a shadow pass
  • post - a post-process pass

type

A type of the texture.

Available values:

  • image - a standard texture image
  • alpha_fade - a texture with the alpha channel
  • environment - an environment texture
  • deferred_depth - a texture using a deferred buffer to store depth values
  • deferred_color - a texture using a deferred buffer to store diffuse values
  • deferred_normal - a texture using a deferred buffer to store normal and specular values
  • deferred_parallax - a texture using a deferred buffer to store parallax offset values
  • deferred_occlusion - a texture using a deferred buffer to store occlusion values
  • deferred_light - a texture using a deferred buffer to store light values
  • light_image - a texture storing the light values provided by projected light sources
  • light_color - a texture storing light color values obtained after the light passes applying for translucent objects
  • light_depth - a texture storing depth values (used to render shadows)
  • light_noise - a texture storing 3D noise values (used to render soft shadows)
  • light_vcube - a texture mapping coordinates of the special 2D depth texture to cube map coordinates
  • reflection_2d - a texture storing reflection values (used to render 2D reflections)
  • reflection_cube - a texture storing reflection values (used to render cube-mapped reflections)
  • downsize - a downsized texture
  • procedural - a procedurally generated texture
  • filter - a filtering texture

unit

A number of the Texture Mapping Units to be used.

format

A texture format.

Available values:

  • srgb - a standard RGB color space format
  • signed - a signed normalized format

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

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 

States Attributes

For the texture field to be displayed only if the state is set to a definite value, the corresponding state should be specified as an attribute for the texture. For example, if you want the texture, lets name it "auxiliary", to be displayed only if the specified Auxiliary pass is enabled, specify the following:

XML Code
<texture name="auxiliary" auxiliary="1"></texture>

materials

A list of post-process materials to be used.

Shader Element

A <shader/> element allows you to specify vertex, fragment and geometry shaders to be used for the described pass.

Notice
You can use GLSL and HLSL shading languages to write shaders.

pass

A pass for the shader to be applied.

Available values:

  • wireframe - a wireframe pass
  • deferred - a deferred pass
  • auxiliary - an auxiliary pass
  • refraction - a refraction pass
  • velocity - a velocity pass
  • ambient - an ambient pass
  • light_prob - a prob light pass
  • light_spot - a spot light pass
  • light_omni - an omni-directional light pass
  • light_proj - a projected light pass
  • light_world - a world light pass
  • translucent - a translucent pass
  • shadow - a shadow pass
  • post - a post-process pass

object

An object to which a shader will be applied.

Available values:

defines

A list of the shader definitions to be used.

Notice
An example of a defines attribute usage is shown in the Custom Materials article.

vertex

A path to the vertex shader to be used.

geometry

A path to the geometry shader to be used.

fragment

A path to the fragment shader to be used.

Usage Example

An example of the ambient pass shader, applied to the dynamic mesh:

Source code (XML)
<shader pass="ambient" object="mesh_dynamic"
	vertex="shaders/vertex.shader"
	geometry="shaders/geometry.shader"
	fragment="shaders/fragment.shader"/>

Bind Element

Each <shader/> element specifies an object to which the shader will be applied, so if, for example, you have shaders for the mesh object, the material could not be applied to the clutter object. A <bind/> element allows you to apply shaders written for one type of objects to another types of objects, so you can just bind a clutter object to the mesh for the shader to be applied for it.

object

And object to be binded.

Available values:

to

And object to bind.

Available values are the same as for object attribute.

defines

A list of the definitions to be used if the material is binded.

Usage Example

An example of binding a mesh skinned object to a mesh object (with the mesh skinned definition):

Source code (XML)
<bind object="mesh_skinned" to="mesh" defines="MESH_SKINNED"></bind>

Parameter Element

A <parameter/> element specifies parameters of the material, their types and default values.

name

Name of the parameter.

type

A type of the parameter, specifying what type of value the parameter accepts.

Available values:

  • constant - accepts only a constant value
  • color - accepts only a color value (a quad of floats corresponding to RGBA color components)
  • slider - accepts values only from a continuous range of allowed values
  • expression - accepts expressions
  • array - accepts a vec4 data type

shared

A flag indicating if the parameter will be exported to the shader.

Available values:

  • 0 - parameter is not exported (by default)
  • 1 - parameter is exported

min and max

Minimum and maximum available values of the parameter.

flags

A flags attribute allows you to specify some additional conditions for the parameters of the slider type.

Available values:

  • srgb - indicates that a given parameter uses automatic conversion to sRGB inside the render
  • log10 - indicates that a given parameter uses a logarithmic scale (with the base ten)
  • max_expand - indicates that the specified maximum value of the parameter can be increased
  • min_expand - indicates that the specified maximum value of the parameter can be decreased

States Attributes

For the parameter field to be displayed only if the state is set to a definite value, the corresponding state should be specified as an attribute for the parameter. For example, if you want the parameter, lets name it "auxiliary", to be displayed only if the specified Auxiliary pass is enabled, specify the following:

XML Code
<parameter name="auxiliary" auxiliary="1"></parameter>

Usage Example

An example of different types of parameters declaration:

Source code (XML)
<parameter name="expression_parameter" type="expression" shared="1">vec4(1.0f,1.0f,0.0f,0.0f)</parameter>
<parameter name="slider_parameter" type="slider" shared="1" min="0.0" max="4.0" flags="max_expand">1.0</parameter>
<parameter name="color_parameter" type="color" shared="1">1.0 1.0 1.0 1.0</parameter>
<parameter name="constant_parameter" type="constant" shared="1">0.0 0.0 0.0 0.0</parameter>
<parameter name="array_parameter" type="array" shared="1"/>
Last update: 03.07.2017
Build: ()