Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
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

water_base

A water_base material simulates water and other liquids. It can be applied to object water and water meshes.

Notice
Water meshes must be exported at the center of world coordinates; otherwise, some effects (for example, caustics) may not be rendered correctly.

States

In the States tab you can set rendering passes and available options. Enabling some of the states activates additional textures and parameters in the Textures and Parameters tabs respectively.

For this material states divide into 3 groups: Passes, Reflection and Options.

Possible values for all the passes:

GUI name XML name Description
Skip none Material is not rendered during the pass.
Default default Material is rendered during the pass.

Possible values for an Map size reflection parameter:

GUI name XML name Description
128 128 A size of the reflection image is 128 pixels.
256 256 A size of the reflection image is 256 pixels.
512 512 A size of the reflection image is 512 pixels.
1024 1024 A size of the reflection image is 1024 pixels.
2048 2048 A size of the reflection image is 2048 pixels.
quart_height quart_height A size of the reflection image is a quart of the height value.
half_height half_height A size of the reflection image is a half of the height value.
height height A size of the reflection image is equal to the height value.

Possible values for an Filter reflection parameter:

GUI name XML name Description
Skip disabled Reflection image is not filtered.
One pass 1x Reflection image is filtered during the one pass.
Two passes 2x Reflection image is filtered during two passes.
Three passes 3x Reflection image is filtered during three passes.
Four passes 4x Reflection image is filtered during four passes.

All the other reflection options can be either enabled or disabled by ticking the respective boxes.

All the options can be either enabled or disabled by ticking the respective boxes.

All the states can be set to default ones - click a Set to parent button near the state (if the state is different from the default one, its field will be highlighted with green).

The states available for this kind of materials are listed below.

Passes

Passes specify during which rendering pass the material should be rendered. They are modified in the Passes field of the States tab.

GUI name XML name Description
Deferred deferred Deferred rendering pass. Specifies if the material should be rendered during the deferred pass. For the transparent surfaces see also a Post deferred option.
Auxiliary auxiliary Auxiliary rendering pass. Specifies if the material should be rendered into the auxiliary buffer to create a custom post-process.
Light omni light_omni Omni-directional lights rendering pass. Specifies, if the material should be rendered illuminated by the Omni light sources during the light and shadows rendering passes.
Light proj light_proj Projected lights rendering pass. Specifies, if the material should be rendered illuminated by the Projected light sources during the light and shadows rendering passes.
Light world light_world World lights rendering pass. Specifies, if the material should be rendered illuminated by the World light sources during the light and shadows rendering passes.

Reflection

The following reflection options are set in the Reflection field of the States tab.

GUI name XML name Description
Dynamical reflection_dynamic Specifies if the reflection is dynamic. Disabling this parameter specifies that the static reflection texture will be added.
Map size reflection_size Specifies the size of the reflection in pixels.
Filter reflection_filter Specifies the amount of rendering passes for the post-process filter.
Shared reflection_shared Specifies if the reflection will be shared with all the nodes across nodes hierarchy.
Shadow reflection_shadow Specifies if shadows will be rendered in the reflection.
TwoSided reflection_two_sided Specifies if the reflection is two-sided.

Options

The following options are set in the Options field of the States tab.

GUI name XML name Description
Subsurface subsurface Specifies if the additional subsurface scattering layer should be rendered. It becomes most visible at the horizon when the viewing angle is close to the water surface.
Disabled Subsurface Enabled Subsurface
Disabled Subsurface
Enabled Subsurface
Foam foam Specifies if the foam along the shore should be rendered.
Foam
Foam
Caps caps Specifies if white caps should be rendered. White caps look much like foam, except that they are spread all over the water surface.
Caps
Caps
Caustics caustics Specifies if caustics on the underwater surfaces should be rendered.
Caustics
Caustics
Spacer interaction spacer Specifies if an interaction with the FieldSpacer objects is enabled.
Ambient light ambient_light Optimizes water rendering. When enabled, water is rendered only once - during the ambient rendering pass, and are not redrawn one more time for a world light pass (it is automatically skipped in this case).

Textures

In the Textures tab of the Materials Editor you can:

  • Load the textures - click a Load button near the texture and specify the path to the texture or type the path in the texture field manually
  • Open the view window to see texture's details - click a View button near the texture
  • Set the current texture to default one - click a Set to parent button near the texture (if the texture is different from the default one, its field will be highlighted with green)

The textures available for this kind of materials are listed below.

Base Textures

Base textures are loaded and modified in the Base field of the Textures tab. Normal and specular textures are present only if Phong Shading option in the States tab is enabled.

GUI name XML name Description Channels
Normal 01normal_01Normal map used to create the first layer of waves. RG:
  • RG values contain two components of a normal
  • The third component's value is calculated from the given components in run-time
Normal 23normal_23Normal map used to create the second layer of waves. RG:
  • RG values contain two components of a normal
  • The third component's value is calculated from the given components in run-time

The rippling is simulated in the following way:

  1. The 1st layer of waves is computed using Normal 01 texture:
    1. Normal 0 expression transforms it and the 1st transformation layer is stored.
    2. Normal 1 expression transforms it and the 2nd transformation layer is stored.
    3. Transformation layers are summed.
  2. The 2st layer of waves is computed using Normal 23 texture:
    1. Normal 2 expression transforms it and the 1st transformation layer is stored.
    2. Normal 3 expression transforms it and the 2nd transformation layer is stored.
    3. Transformation layers are summed.
  3. Two resulting transformations are summed once again to be rendered on the water surface.

Additional Textures

Additional textures are present only if a Foam and Caps options in the States tab are enabled and are modified in the Additional field of the Textures tab.

GUI name XML name Description Channels
Foamfoam Additional one channel texture for foam along the shore. R
Capscaps Additional one channel texture for white caps across the water surface. R

Reflection Textures

Reflection static texture is present if a Dynamic option is in the Reflection field of the States tab id disabled. The texture can be loaded and modified in the Reflection field of the Textures tab.

GUI name XML name Description Channels
Static reflection Static reflection mask. A texture to store reflection information. RGB values store a reflection mask of the specified value.

Parameters

In the Parameters tab you can set or modify base and additional parameters.

Parameters of different types are set in different ways:

  • expression - vector values can be set either in the field near the parameter or in the dialog window opened when double clicking this field
  • slider - the value can be set either by smoothly moving the slider of the scroll box or manually in the box near the parameter (if required, the value bigger than maximum one for the slider can be set)
  • color - the color can be chosen in the dialog window, activated after double clicking the color field

All the parameters can be set to default ones - click a Set to parent button near the parameter (if the parameter is different from the default one, its field will be highlighted with green).

The parameters available for this kind of materials are listed below.

Transform Parameters

Texture transformation parameters are modified in the Transform field of the Parameters tab.

GUI name XML name Type Description
Normal 0 normal_0_transform expression Normal 01 texture first layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Normal 1 normal_1_transform expression Normal 01 texture second layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Normal 2 normal_2_transform expression Normal 23 texture first layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Normal 3 normal_3_transform expression Normal 23 texture second layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.

Foam transformation parameters are present only if a Foam option in the States tab is enabled and applied to the foam texture.

GUI name XML name Type Description
Foam 0 foam_0_transform expression Foam texture first layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Foam 1 foam_1_transform expression Foam texture second layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.

Caps transformation parameters are present only if a Caps option in the States tab is enabled and applied to the caps texture.

GUI name XML name Type Description
Caps 0 caps_0_transform expression Caps texture first layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Caps 1 caps_1_transform expression Caps texture second layer coordinates transformation. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.

Caustics texture transformation parameters are present only if a Caustics option in the States tab is enabled. Two layers of caustics are created based on Normal 01 texture and are rendered in motion.

GUI name XML name Type Description
Caustics 0 caustic_0_transform expression Native coordinates transformation of the first normal map sample. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.
Caustics 1 caustic_1_transform expression Native coordinates transformation of the first normal map sample. A vector of the four float components, consisting of two pairs of vector elements:
  1. Scale texture coordinates, along X and Y axes.
  2. An offset of the texture respectively to its initial position along X and Y axes.

Notice
Besides the native texture coordinates transformation, there are more options of setting texture coordinates. They are described in the Texture coordinates transformation article.

Auxiliary Parameters

Auxiliary color parameter is present only if an Auxiliary pass is set as a Default. The parameter is modified in the Auxiliary field of the Parameters tab.

GUI name XML name Type Description
Color auxiliary_color color A color picker to choose an auxiliary color for the Auxiliary rendering pass.

Reflection Parameters

Reflection parameters are modified in the Reflection field of the Parameters tab. Mask and Distance parameters are present only when the Dynamical option in the States tab is enabled.

GUI name XML name Type Description
Mask reflection_mask expression A mask that specifies materials to reflect.

Each bit of the value contains a separate mask.
Distance reflection_distance expression Distance of reflection rendering in units.
Normal reflection_normal slider A coefficient that determines distortion of the reflection on the water according to the resulting normal map.

By the minimum value of 0, the water reflection is not distorted and the water seems tranquil.

Increasing the value leads to more intense distortion and creates an effect of the more rough surface with capillary waves.
Power reflection_power slider A coefficient to correct the normal map distortion for reflections according to the distance. This parameter allows to compensate for lower resolution of normal map mipmaps in the distance and decrease the rendering load.

By the minimum value of 0, there is no correction. Reflections are distorted according to the normal map across the whole surface of the water.

High values result in distant reflections not being distorted, while the nearby ones are rendered distorted. The higher the value, the less intense normal map distortion is even on closest reflections.
Angle reflection_angle slider A coefficient to control the border between near and far reflections:

By the minimum value of 1, far color is modulating reflections across the whole water surface.

The higher the value, the more nearby reflections are modulated with the near color, while far color is used only near the horizon.
Near color reflection_0_color color A color picker to choose a color for reflections nearby the camera.
Far color reflection_1_color color A color picker to choose a color for reflections on the horizon. This option allows to darken the water near the horizon to achieve true-to-life appearance:
  • Dark Far colors correspond to stormy waters
  • Light Far colors correspond to calm waters

Refraction Parameters

Refraction parameters are modified in the Refraction field of the Parameters tab.

GUI name XML name Type Description
Scale refraction_scale slider A coefficient to scale the intensity of light beams refraction and underwater image distortion.

By the value of 0 there is no underwater surfaces distortion.

The higher the positive value, the more prominent refractive properties are and more intense the underwater distortion is.

Negative values invert the direction of distortion: the lower the negative value, the bigger a distortion is.
Power refraction_power slider A coefficient to scale the correction of refraction according to the distance.

By the minimum value of 0, refraction does not fade out with the distance. Far objects are distorted in the same way as nearby ones.

By high values, there is no refraction for the far objects; only nearby ones are rendered distorted.

The higher the value, the less intense refraction is even at close range from the camera.

Animation Parameters

Animation parameters are modified in the Animation field of the Parameters tab.

GUI name XML name Type Description
Waves radius wave_radius slider Distance in units that limits rendering of geometrical waves, starting from the camera and up to the specified distance. This parameter allows to avoid moire patterns in the distance.

The higher the value, the further to horizon the waves are spread.

By the value of 0, there are no geometrical waves.

Surface Parameters

Surface parameters are modified in the Surface field of the Parameters tab.

GUI name XML name Type Description
Color volume_color color A color picker to choose the color of the water surface. It can be used to create an effect of muddy water.

The brighter the color, the less transparent the water appears.

In case of completely black surface color, shadows may not be visible on the water surface.
Density volume_density slider Density of the water surface that determines softness of the surface line and how close to the shore line water reflections are. It also influences the visibility of foam.

Low values result in a surface slightly tinted and soft surf line. The foam is hardly present.

High values result in a saturated color, as well as clear and sharp contour of the surf line and distinct foam.

Volume Parameters

Volume parameters are modified in the Volume field of the Parameters tab.

GUI name XML name Type Description
Color volume_color color A color picker to choose the color of the underwater volume simulating depth.
Power volume_power slider Density fall-off of the underwater volume that controls the smoothness of the volume spread line (the depth changing line between shallow waters and deep areas).

By the minimum value of 1, the underwater density increases smoothly and broadly.

The higher the value, the more abrupt the line of transition is.
Density volume_density slider Density of the underwater volume that determines the position of the volume spread line (the line of shallow waters changing into the deep areas).

Low values result in a lengthy shallow area.

High values result in water rapidly growing deep close to the shore, at the expense of shallow area shortening.

Subsurface Parameters

Subsurface parameters are present if the Subsurface option in the States tab is enabled and are modified in the Subsurface field of the Parameters tab.

GUI name XML name Type Description
Color subsurface_color color A color picker to choose the color of the water subsurface scattering layer.
Power subsurface_power slider Density fall-off of the subsurface that controls the smoothness of subsurface layer spread line.

By the minimum value of 1, the density of the subsurface scattering layer increases smoothly and broadly.

The higher the value, the more abrupt the line of transition is.
Density subsurface_density slider Density of the of the subsurface scattering layer that defines the position of the layer spread line.

Low values result in the subscattering layer is very thin and visible only near the horizon line.

High values result in the subscattering layer is spread closer to the camera.
Falloff subsurface_falloff slider Foam fall-off that determines the extent of foam spread.

Low values lead to extensive foam distribution.

Increasing the value result in foam spread narrower and concentrated closer to the shore.

Foam Parameters

Foam parameters are present if the Foam option in the States tab is enabled and are modified in the Foam field of the Parameters tab.

GUI name XML name Type Description
Color foam_color color A color picker to choose the color of the foam.
Scale foam_scale slider A coefficient to scale the foam color intensity.

By the minimum value of 0, there is no foam at all.

The higher the value, the brighter a foam color is.
Threshold foam_threshold slider Foam threshold. If the foam color in some point is brighter than this value, the foam is rendered in that point.

By the minimum value of 0, the whole surface line is abound with foam.

Increasing the value results in scarcer foam until completely disappearing.
Falloff foam_falloff slider Foam fall-off that determines the extent of foam spread.

Low values lead to extensive foam distribution.

Increasing the value result in foam spread narrower and concentrated closer to the shore.

Caps Parameters

Caps parameters are present if the Caps option in the States tab is enabled and are modified in the Caps field of the Parameters tab.

GUI name XML name Type Description
Color caps_color color A color picker to choose the color of the white caps.
Multiplier caps_scale slider A coefficient to scale the white caps color intensity.

By the minimum value of 0, there is no white caps at all.

The higher the value, the more visible the white caps are.
Threshold caps_threshold slider Caps threshold. If the caps color in some point is brighter than this value, white caps are rendered in that point.

By the minimum value of 0, the whole water surface is white due to white caps.

Increasing the value results in smaller white caps until they completely disappear.

Caustics Parameters

Caustics parameters are present if the Caustics option in the States tab is enabled and are modified in the Caustics field of the Parameters tab.

GUI name XML name Type Description
Color caustic_color color A color picker to choose the color of caustics.
Power caustic_power slider Power parameter allows to fine-tune Threshold to render caustics.

For example, setting high Threshold and increasing the Power will result in the following: caustics is subtle and it smoothly fades out. If only Threshold is used, caustics will have rough outline.

Increasing the Power value results in finer and less visible caustics.

Notice
If caustics Threshold equals 0, Power is not applied.
Power with Threshold Only Threshold
Power with high Threshold
Only Threshold (Power = 0)
Multiplier caustic_scale slider A coefficient to scale the visibility of the caustics.

By the minimum value of 0, there is no caustics effect visible.

The higher the value, the brighter caustics color is.
Threshold caustic_threshold slider Caustic threshold. If in some point the normal map is higher (brighter) than the threshold value, caustic is rendered in that point.

By the minimum value of 0, underwater surfaces will be rendered of homogeneous caustics color.

The higher the value, the finer the caustics pattern is.
Density caustic_density slider Density of water, that determines the spread of caustics patterns into the shallow areas.

Low values determine caustics patterns appear starting far from the surf line.

High values result in caustic patterns appear right on the brink of water.
Falloff caustic_falloff slider Caustic fall-off that determines the spread of caustics patterns into the deep areas.

Low values allow to simulate caustics on underwater surfaces lying deep.

High values result in caustics effect limited to the shallow areas.

Ambient Parameters

Ambient parameter is modified in the Ambient field of the Parameters tab.

GUI name XML name Type Description
Environment environment_scale slider Environment lighting scale. A coefficient to scale how much the global environment texture illuminates the surface.

The higher the value, the more the colors will be corrected (lightened or darkened) according to the environment component.

Shading Parameters

Shading parameters are modified in the Shading field of the Parameters tab.

GUI name XML name Type Description
Diffuse diffuse_scale slider A coefficient to scale the brightness of the water surface color.

The higher the value, the brighter the color is.
Specular specular_scale slider A coefficient to scale the intensity of the glints on the water surface.

The default value of 1 grants the correct color. The higher the value, the more intensive the glints are.
Glossiness specular_power slider

A coefficient to modify size of the highlight (Phong lighting) of the specular map:

  • Low values imitate wider highlights, typically appropriate to create diffuse reflection from the mat surface
  • High values imitate pinpoint highlights, typically appropriate to create uniform reflection of light rays from the glossy surface
Fresnel bias fresnel_bias slider A coefficient to compensate for the Fresnel effect and set the minimum necessary reflectance level.

By the minimum value of 0, there is no compensation for the Fresnel effect.

Increasing the value leads to more prominent overall reflections.

By the maximum value of 1, reflections are at their maximum and the Fresnel power parameter does not influence the rendered image.
Fresnel power fresnel_power slider

A coefficient to scale Fresnel effect that defines the amount of reflectance depending on the viewing angle:

  • Low values provide good reflectance even at a large viewing angles
  • High values provide the reflectance only at a small viewing angles. When looking at a large viewing angle, from above, there are no reflections rendered
Last update: 2017-07-03