Material File Format

A version of the .mat file.

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

Available values:

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

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

Available values:

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

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

Available values:

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

The unique name of a material.

The name of a parent material.

The prefix added to all material parameters when they are passed to the shader.

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

<material name="custom_base" parameters_prefix="m" editable="0">
...
</material>

Name of the state.

A flag indicating whether the state is hidden in the Materials editor.

A type of the switch between the state values.

Available values:

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

A set of available items for a multiple values switch.

The attribute that specifies names of definitions that will be passed to the shader:

name

<state name="vertex_color" defines="name"/>

items

<state name="workflow" items="metalness,specular" defines="items"/>

name_items

<state name="opacity_map" transparent="1,2" items="main,normal" defines="name_items"/>

The attribute that specifies passes to which the definitions will be passed.

deferred

all

forward

depth_pre_pass

auxiliary

refraction

velocity

ambient

emission

light_omni

light_proj

light_world

shadow

transparent

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

<state name="parallax_shadow" parallax="1" transparent="0,1"/>

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

<state name="deferred" type="switch" items="none,default">1</state>

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.

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

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.

A light viewport mask.

Available values:

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

A viewport mask.

Available values:

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

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

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

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

Available values:

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

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

<options alpha_test="1"/>

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

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.

For example, if you want the opaque areas to receive a material color and transparent areas to receive a screen buffer color, type:

<blend src="one" dest="one_minus_src_alpha"/>

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

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

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

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

A number of the Texture Mapping Units to be used.

A texture format.

Available values:

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

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

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

Available values:

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

A type of the texture filtering.

Available values:

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

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:

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

A list of post-process materials to be used.

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

An object to which a shader will be applied.

Available values:

• dynamic - a dynamic object
• mesh - a static mesh
• mesh_cluster - a mesh cluster
• mesh_clutter - a mesh clutter
• mesh_skinned - a skinned mesh
• mesh_dynamic - a dynamic mesh
• terrain - a terrain object
• grass - a grass object
• particles - particles
• billboards - billboards
• volume_box - a volume box
• volume_sphere - a volume sphere
• volume_omni - a volume omni object
• volume_proj - a volume projected object
• gui - a GUI object
• gui_mesh - a GUI mesh
• water - a water object
• water_mesh - a water mesh
• sky - a sky object

A list of the shader definitions to be used.

A path to the vertex shader to be used.

A path to the geometry shader to be used.

A path to the fragment shader to be used.

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

<shader pass="ambient" object="mesh_dynamic"
	vertex="shaders/vertex.shader"
	geometry="shaders/geometry.shader"
	fragment="shaders/fragment.shader"/>

And object to be binded.

Available values:

• dynamic - a dynamic object
• mesh_static - a static mesh
• mesh_cluster - a mesh cluster
• mesh_clutter - a mesh clutter
• mesh_skinned - a skinned mesh
• mesh_dynamic - a dynamic mesh
• terrain - a terrain object
• grass - a grass object
• particles - particles
• billboards - billboards
• volume_box - a volume box
• volume_sphere - a volume sphere
• volume_omni - a volume omni object
• volume_proj - a volume projected object
• gui - a GUI object
• gui_mesh - a GUI mesh
• water - a water object
• water_mesh - a water mesh
• sky - a sky object

And object to bind.

Available values are the same as for object attribute.

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

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

<bind object="mesh_skinned" to="mesh" defines="MESH_SKINNED"></bind>

Name of the parameter.

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
• combiner - combines different parameters so the correct value will be passed to the shader. For example, first parameter is vec4 and second is slider. The combiner will combine a vec4 value out of the specified two values (the fourth component of the first parameter will be discarded and the slider value will be used instead).

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

Minimum and maximum available values of the parameter.

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

Available values:

• log10 - indicates that a given parameter uses a logarithmic scale (with the base ten)
• expand - indicates that the specified maximum and minimum values of the parameter can be exceeded.
• 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

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:

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

An example of different types of parameters declaration:

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