This page has been translated automatically.
编程
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
应用程序接口
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
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

Base Material File Format

Base Material File Structure

A base material is a *.basemat ("Base Material") text file that contains all of the information to provide a required image. The base material is created by programmers and cannot be edited via Material Editor: its properties can be adjusted and assets can be set only in the text file.

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 *.basemat 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 *.basemat file elements, attributes and values are listed below.

Notice
Unigine has the limit of 32767 material parameters.

Base Material Element

A <base_material/> element defines a base material with the given properties (options, states, textures, parameters, shaders). Elements inside the <base_material/> element can be arrange freely (for example, you can specify parameters first and then add states).

It can have the attributes listed below.

version

A version of the .basemat file.

name

A name of the base material. Materials inherited from the base material refer to it by the name. The name is also used to generate the GUID for the base material in runtime.

guid

A GUID for the base material.

The guid attribute is optional. The GUID for the base material will be generated from its name in runtime, if the guid attribute isn't specified.

parameters_prefix

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

defines

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

editable

A flag, indicating if all the base material settings can be changed in the Materials editor.

Available values:

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

hidden

A flag, indicating if a material is displayed in the material list of the Materials editor.

Available values:

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

Usage Example

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

Source code (XML)
<base_material version="2.0"  name="custom_base" parameters_prefix="m" editable="0">
...
</base_material>

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.

Options Element

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

It can have the attributes listed below.

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.

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 Dept 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 light shadows are enabled/disabled for a material.

Available values:

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

receive_world_shadow

A flag indicating if world light shadows are enabled/disabled 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.

Group Element

A <group/> element specifies the group which states, textures or parameters of the base material belong to. The element is optional: states, textures or parameters can be defined out of it. You can also specify the group attribute for the <state/>,<texture/> or <parameter/> element instead of using the <group/> element.

name

Name of the group.

Usage Example

For example, some states of the mesh_base material can be grouped as follows:

Source code (XML)
<base_material version="2.0" name="mesh_base" editable="0" parameters_prefix="m" defines="VERTEX_ATTRIBUTE_GEOMETRY">
	<group name="Default">
		<state name="workflow" items="metalness,specular" defines="items"/>
		<state name="deferred" title="Deferred Buffers" tooltip="Deferred buffers rendering">1</state>
		<state name="multiple_environment_probes" transparent="2" defines="name">0</state>
	</group>
</base_material>

Or the group attribute can be used instead of the corresponding element:

Source code (XML)
<base_material version="2.0" name="mesh_base" editable="0" parameters_prefix="m" defines="VERTEX_ATTRIBUTE_GEOMETRY">
	<state name="workflow" items="metalness,specular" defines="items" group="Default"/>
	<state name="deferred" title="Deferred Buffers" group="Default">1</state>
	<state name="multiple_environment_probes" transparent="2" defines="name" group="Default">0</state>
</base_material>

Supported Element

A <supported/> element allows you to specify types of nodes to which the material can be applied.

Notice
The element should be used when no shaders and bindings are specified for the material.
For example, the clouds_base base material uses the <supported/> element, as this material doesn't have a shader.

One element allows specifying only one type of the node.

Source code (XML)
<supported node="object_dynamic"/>
<supported node="object_mesh_dynamic"/>
...
<supported node="object_mesh_static"/>

node

A name of the node.

Available values:

State Element

A <state/> element allows you to set a mode for rendering passes and a value for rendering options. The states change a set of definitions passed to shaders, so any changes made to a state cause recompiling shaders.

name

Name of the state.

hidden

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

type

A type of the the state value.

Available values:

  • toggle - a switch that enables/disables the state
  • switch - a multiple values switch
  • int - an integer value

items

A set of available items for a multiple values switch.

defines

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

name

A name specified via name.

Source code (XML)
<state name="vertex_color" defines="name"/>

In the example above the following definition will be passed to the shader: VERTEX_COLOR.

items

A set of multiple values specified via items (in the upper case).

Source code (XML)
<state name="workflow" items="metalness,specular" defines="items"/>

In the example above the following definitions will be passed to the shader: METALNESS and SPECULAR.

name_items

A name specified via name followed by a set of multiple values specified via items.

Source code (XML)
<state name="opacity_map" transparent="1,2" items="main,normal" defines="name_items"/>

In the example above the following definitions will be passed to the shader: OPACITY_MAP_MAIN and OPACITY_MAP_NORMAL.

pass_defines

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

all

Specifies if the material is rendered during all the passes.

deferred

Specifies if the material is rendered into the deferred buffer during the deferred rendering pass (i.e. all passes for opaque geometry).

forward

Specifies if the material is rendered during the forward rendering pass including environment probe light, omni light, projected light, world light and ambient passes.

depth_pre_pass

Specifies if the material is rendered into the depth buffer during the native depth pre-pass.

auxiliary

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

refraction

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

velocity

Specifies if the material is rendered during the velocity pass.

ambient

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

emission

Specifies if the material is rendered during the emission rendering pass.

light_omni

Specifies if the material is rendered illuminated by the omnidirectional light sources during the omni light pass.

light_proj

Specifies if the material is rendered illuminated by the projected light sources during the projected light pass.

light_world

Specifies if the material is rendered illuminated by the world light sources during the world light pass.

light_environment_probe

Specifies if the material is rendered illuminated by the environment probes during the environment probe rendering pass.

light_all

Specifies if the material is rendered illuminated by the all lights in the scene during the environment probe light, omni light, projected light, world light passes.

shadow

Specifies if the material is rendered during the shadows rendering pass.

transparent

Specifies if the material is rendered during the forward, refraction and transparent blur passes.

wireframe

Specifies if the material is rendered during the wireframe pass.

visualizer_solid

Specifies if the material is rendered during the visualizer solid pass.

reflection

Specifies if the material is rendered during the reflection pass.

transparent_blur

Specifies if the transparent blur effect is used for the material rendered during the transparent blur pass. This effect allows creating a matte transparent materials.

post

Specifies if the material is rendered during the post materials rendering pass.

object_post

Specifies if the material is rendered during the object post materials pass.

title

A state title that will be displayed in the editor.

Notice
Available only in Editor2.

tooltip

A tooltip for a state. The tooltip will be displayed in the editor when the state is pointed with the mouse.

Notice
Available only in Editor2.

group

A group which a state belongs to. The attribute can be used instead the group element.

Notice
Available only in Editor2.

widget

A type of the widget reqiured to set a state value.

internal

A flag indicating if the state is internal (i.e. cannot be changed via UnigineEditor but used by internal logic). The child materials don't inherit internal states, so callbacks on these states aren't fired for them.

Available values:

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

State Conditions

A state can have a condition specified as an attribute. For example, the following state will be displayed when the transparent option is set to Opaque or Alpha test and the Parallax state is enabled:

Source code (XML)
<state name="parallax_shadow" parallax="1" transparent="0,1"/>

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. The up-to-date set of built-in names of textures can be found in data/editor/editor_material_textures.h)

Values used by the built-in base materials:

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

pass

A pass during which a texture will be rendered.

Available values:

  • wireframe - the wireframe pass
  • visualizer_solid - the visualizer solid pass
  • deferred - the deferred pass
  • auxiliary - the auxiliary pass
  • emission - the emission pass
  • refraction - the refraction pass
  • reflection - the reflection pass
  • transparent_blur - the transparent blur pass
  • ambient - the ambient pass
  • light_environment_probe - the environment probe pass
  • light_omni - the omni-directional light pass
  • light_proj - the projected light pass
  • light_world - the world light pass
  • light_all - the environment probe, omni-directional light, projected light, world light passes
  • depth_pre_pass - the native depth pre-pass
  • shadow - the shadows pass
  • post - the post-process pass
  • object_post - the object post-process pass
  • forward - the environment probe, omni-directional light, projected light, world light and ambient passes
  • transparent - the forward, refraction, transparent blur passes

type

A type of the texture.

Available values:

  • image - a standard texture image (by default).
  • gbuffer_albedo - a texture that uses the G-buffer to store albedo values.
  • gbuffer_shading - a texture that uses the G-buffer to store shading data.
  • gbuffer_normal - a texture that uses the G-buffer to store normal values.
  • gbuffer_velocity - a texture that uses the G-buffer to store velocity values.
  • gbuffer_material_mask - a texture that uses the G-buffer to store material mask data.
  • gbuffer_lightmap - a texture that uses the G-buffer to store lightmap values.
  • gbuffer_geodetic_flat_position - a texture that uses the G-buffer to store flat plane coordinates.
  • auxiliary - an auxiliary texture that is used for different post effects (an auxiliary pass).
  • refraction - a texture that stores refraction data.
  • transparent_blur - a 1-channel R16F mask that stores intensity of blurring for transparent materials. The mask specifies where to blur the material.
  • lights - a 2D array texture of the RG11B10F format that stores diffuse light in the first layer (RGB) and specular light in the second layer (RGB).
  • environment_probes - a 2D array texture of the RGBA16F format that stores reflections in the first layer (RGBA) and ambient lights in the second layer (RGBA).
  • bent_normal - an RG11B10F texture that stores bent normals (RGB) used for smooth ambient lighting.
  • ssao - a texture that stores SSAO (Screen Space Ambient Occlusion) data.
  • ssgi - a texture that stores SSGI (Screen Space Global Illumination) data.
  • ssr - a texture that stores SSR (Screen Space Reflections) data.
  • ssr_depth - a texture that stores SSR (Screen Space Reflections) depth data.
  • dof_mask - a texture that stores a DoF (Depth of Field) mask.
  • auto_exposure - an RG16F texture that stores intensity of the exposure (R) and luminance (G).
  • screen_color - a texture that stores screen color data and can be used for post effects.
  • screen_color_old - a texture that stores Color Old (previous frame) data.
  • screen_color_old_reprojection - a texture that stores Color Old (previous frame) Reprojection data.
  • normal_unpack - a texture that stores unpacked normals. Available for the following post-effects: SSR, SSGI, SSRTGI, Shadows screen space.
  • current_depth - a texture that stores current depth data for all geometry on the scene.
  • opacity_depth - a texture that stores depth data for opacity geometry and can be used for soft particles and volumetrics.
  • linear_depth - a texture that stores linear depth data.
  • opacity_screen - a texture that stores the deferred composite and emission data.
  • light_image - a texture storing the light values provided by projected light sources.
  • light_depth - a texture storing depth values (used to render shadows).
  • transparent_environment_probes - a texture that stores environment probes rendered on transparent objects. Available only when Multiple environment probes are enabled.
  • 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).
  • scattering_sky_lut - a texture that stores sky scattering LUT data.
  • scattering_ground_lut - a texture that stores ground scattering LUT data.
  • wbuffer_constant_id - a constant texture, R32U. A texture of this type stores the ID value of the water mesh which is used to load the corresponding textures and parameters for it.
  • wbuffer_diffuse - a diffuse texture. The diffuse color of the water is black, and diffuse texture is necessary for decals, that will be displayed over the water surface
  • wbuffer_normal - a normal texture stores normal data for lighting, and alpha channel stores mesh transparency values (it can be used for soft intersections with water geometry)
  • wbuffer_water - a water texture, RG8. It is used to create the procedural foam mask. The mask shows where the foam will be depicted
  • wbuffer_wu_mask - an underwater mask texture, RGB8. The underwater mask is used only for Global water, since water mesh doesn't have an underwater mode
  • wbuffer_ss_environment - an RGBA16 underwater fog texture that stores water bottom coloring values (RGB) and fog transparency (A).
  • clouds_screen - an RGBA16F texture into which clouds are rendered.
  • clouds_static_coverage - a texture that stores clouds static coverage data.
  • clouds_dynamic_coverage - a texture that stores clouds dynamic coverage data.
  • field_height_array - a heightmap texture that is used to create an additional height displacement for water surface.
  • field_shoreline_array - a field shoreline texture.
  • decal_depth - a texture that stores depth data for decals.
  • decal_albedo - a texture that stores albedo color data for decals.
  • decal_normal - a texture that stores normal data for decals.
  • decal_shading -a texture that stores shading data for decals.
  • procedural - a procedurally generated texture.
  • filter - a filtering texture.

unit

A number of the Texture Mapping Unit (slot) to be used for the texture. The unit specifies a slot of a shader, to which the texture will be passed. The maximum available number of units is 32, the first 16 units supports filtering. If the unit is greater or equal 16, no filtering will be used for the texture.

format

A texture format.

Available values:

  • srgb - a standard RGB color space format.
  • signed - a signed normalized format.
  • integer - an integer 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
  • repeat - no wrap, a texture is tiled along all axes.

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 filtering (when enablled, disables anisotropy filtering)  
  • linear   - linear filtering  
  • bilinear   - bilinear filtering  

title

A texture title that will be displayed in the editor.

Notice
Available only in Editor2.

group

A group which a texture belongs to. The attribute is optional: you can use the group element instead.

Notice
Available only in Editor2.

widget

A type of the widget reqiured to set a parameter.

tooltip

A tooltip for a texture. The tooltip will be displayed in the editor when the texture field is pointed with the mouse.

Notice
Available only in Editor2.

hidden

A flag indicating whether the texture is displayed in UnigineEditor.

shader

A shader type to which the texture is binded to.

Available values:

  • all - a texture should be bound to all shaders.
  • fragment - a texture should be bound to fragment shaders only (by default).

materials

A list of post-process materials to be used.

Texture Conditions

A texture can have a condition specified as an attribute. For example, the following texture will be displayed when the transparent option is set to Opaque or Alpha test and the Parallax state is enabled:

Source code (XML)
<texture name="parallax"	parallax="1" transparent="0,1">core/textures/common/red.dds</texture>

Parameter Element

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

name

Name of the parameter.

title

A parameter title that will be displayed in the editor.

Notice
Available only in Editor2.

tooltip

A tooltip for a parameter. The tooltip will be displayed in the editor when the parameter field is pointed with the mouse.

Notice
Available only in Editor2.

group

A group which a parameter belongs to. The attribute is optional: you can use the group element instead.

Notice
Available only in Editor2.

type

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

Available values:

  • constant - accepts only a vec4 value. Despite the type name, the value of such parameter can be changed.
  • color - accepts only a color value (a quad of floats corresponding to RGBA color components).
  • slider - accepts float values only from a continuous range of allowed values.
  • expression - accepts expressions (scripts). The expression is executed each frame.
    Notice
    The expression type should be specified for a mask parameter (e.g. material mask). If you specify an expession except the mask, the mask will always be 0.
  • 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).

Combiner Parameters

For the parameter of the combiner type the names of the combined parameters are used as attributes that specify combiner masks. Available values:

  • XYZW - all values of the parameter are taken into account when combining with the other parameters.
  • XYZ - the 4th component of the parameter isn't taken into account.
  • X - only the 1st component of the parameter is taken into account.
  • Y - only th 2nd component of the parameter is taken into account.
  • Z - only the 3rd component of the parameter is taken into account.
  • W - only th 4th component of the parameter is taken into account.

pass

A pass during which a parameter will be used.

Available values:

  • wireframe - the wireframe pass
  • visualizer_solid - the visualizer solid pass
  • deferred - the deferred pass
  • auxiliary - the auxiliary pass
  • emission - the emission pass
  • refraction - the refraction pass
  • reflection - the reflection pass
  • transparent_blur - the transparent blur pass
  • ambient - the ambient pass
  • light_environment_probe - the environment probe pass
  • light_omni - the omni-directional light pass
  • light_proj - the projected light pass
  • light_world - the world light pass
  • light_all - the environment probe, omni-directional light, projected light, world light passes
  • depth_pre_pass - the native depth pre-pass
  • shadow - the shadows pass
  • post - the post-process pass
  • object_post - the object post-process pass
  • forward - the environment probe, omni-directional light, projected light, world light and ambient passes
  • transparent - the forward, refraction, transparent blur passes

shared

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

Available values:

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

internal

A flag indicating if the parameter is internal (i.e. cannot be changed via UnigineEditor but used by internal logic).

Available values:

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

hidden

A flag indicating if the parameter is hidden in UnigineEditor.

Available values:

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

min and max

Minimum and maximum available values of the parameter.

deferred_unit

A number of deferred units to be used.

shader_name

A name of a shader to which the parameter value is passed. If the prefix or parameters_prefix attribute is specified, it will be used as a prefix for the shader name.

prefix

A prefix for a name of a shader to which the parameter value is passed.

flags

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

Available values:

  • 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

widget

A type of the widget reqiured to set a parameter value.

Available values:

  • mask24 - a widget that allows specifying a 24-bit mask
  • mask32 - a widget that allows specifying a 32-bit mask
  • uv - a widget that allows specifying a UV coordinates
  • vec - a widget that allows specifying vector elements

Parameter Conditions

A parameter can have a condition specified as an attribute. For example, the following parameter will be displayed when the Auxiliary state is enabled:

Source code (XML)
<parameter name="auxiliary_color" 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>

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 - the wireframe pass
  • visualizer_solid - the visualizer solid pass
  • deferred - the deferred pass
  • auxiliary - the auxiliary pass
  • emission - the emssion pass
  • refraction - the refraction pass
  • reflection - the reflection pass
  • transparent_blur - the transparent blur pass
  • ambient - the ambient pass
  • light_environment_probe - the environment probe light pass
  • light_omni - the omni-directional light pass
  • light_proj - the projected light pass
  • light_world - the world light pass
  • depth_pre_pass - the native depth pre-pass
  • shadow - the shadows pass
  • post - the post-process pass
  • object_post - the object post-process pass

node

An object or a decal 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.

*_defines

Options Definitions

A list of the option-specific definitions to be passed to the shader.

A name of such attribute is constructed as follows:

<option_name> + _defines

For example, to specify transparency-related definitions, use the transparent_defines attribute. If the two_sided flag is set for the material, specify the two_sided_defines attribute.

States Definitions

A list of the state-specific definitions to be passed to the shader.

A name of such attribute is constructed as follows:

<state_name> + _defines

For example, to specify transparency-related definitions, use the transparent_defines attribute. If the two_sided flag is set for the material, specify the two_sided_defines attribute.

Notice
An example of the *_defines attributes usage is shown in the Custom Materials article.

vertex

A path to a *.vert vertex shader to be used. If the vertex shader isn't specified, the default core/shaders/common/empty.vert shader will be used.

control

A path to a *.cont control shader (also known as hull) to be used.

evaluate

A path to *.eval evaliation shader (also known as domain) to be used.

geometry

A path to a *.geom geometry shader to be used.

fragment

A path to a *.frag fragment shader to be used.

compute

A path to a *.comp compute shader to be used.

Shader Conditions

A shader can have a condition specified as an attribute. For example, the following shader will be applied when the Auxiliary state is enabled:

Source code (XML)
<shader pass="auxiliary" node="object_mesh_static"
		auxiliary="1"
		defines="BASE_AUXILIARY"
		two_sided_defines=",TWO_SIDED"
		vertex="core/shaders/mesh/auxiliary/auxiliary.shader"
		fragment="core/shaders/mesh/auxiliary/auxiliary.shader"/>

Usage Example

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

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

Bind Element

Each <shader/> element specifies an node 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 nodes to another types of nodes, so you can just bind a clutter object to the mesh for the shader to be applied for it.

node

A node to be binded.

Available values:

to

A node to bind.

Available values are the same as for node 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>

Base Material Conditions

A condition specifies when the state, texture, parameter or shader is displayed in UnigineEditor. The condition is an attribute of the state, texture, parameter or shader element. The following conditions are available:

  • transparent - the element will be displayed when the transparent option is set to the specified value. For example, the Multiple Environment Probes state will be displayed only when the transparent option is set to 2 (the Alpha blend, Additive, Multiplicative or Custom blending preset is used):
    Source code (XML)
    <state name="multiple_environment_probes" transparent="2" defines="name">0</state>
  • An option specified in the options element, except the following: group, order, offset, light_mask, viewport_mask.
  • A state name. For example, the auxiliary_color parameter will be displayed only if the Auxiliary state is enabled:
    XML Code
    <parameter name="auxiliary_color" auxiliary="1" type="color">1.0 1.0 1.0 1.0</parameter>

Notice
The order of conditions declaration and usage doesn't matter: you can specify a condition for an element before this condition is declared in the *.basemat file.
Last update: 2017-12-21
Build: ()