This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Landscape Tool
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Art Samples
Tutorials

Unigine::ObjectWaterGlobal Class

Header: #include <UnigineObjects.h>
Inherits from: Object

Interface for Global Water object handling. This water object represents infinitely spread water with auto-tessellation (the wireframe of the water object is not scaled — regardless of the camera position it stays the same) and the underwater mode. This type is suitable to represent boundless ocean while not overloading the GPU.

However, it cannot have a body assigned, and thus does not provide proper physical interaction with scene objects. If you need to simulate the physics of buoyancy, you should use Physical Water. Also it is limited to a single water level. It means that the filling level of water always remains the same. So, if you need to create, for example, mountain lakes or water flows with height difference, you should use a Water Mesh.

There are two options for creating waves:

  • Layer mode — you create layers on which waves will be randomly generated in a given range of wave parameters. All the layers are added together.
    Notice
    Wave layers are usually created through the UnigineEditor, but you can also create and edit them via code.
  • Manual mode — you create your own individual waves and have full control over them. This mode can only be set via code, you cannot do this in the UnigineEditor.
    Notice
    In Manual mode, be careful with the Steepness parameter, the waves will be everted if this value is set high.

For both Manual mode and Layer mode, wave frequency is calculated based on the wavelength using the formula:

Frequency formula
sqrt (Gravity * 2 * PI / wavelength)

where Gravity = 9.81 m/s2.

When you enable Manual mode, the list of the generated waves is cleared and you can set up your own waves. When you disable Manual mode, the user-defined waves will be cleared, and if you previously had any layers, the waves will be generated based on the parameters of these layers.

When you save the world, the layers will be saved, but the user-defined waves will not, since they are created via code.

The maximum total number of waves is 256. For better performance, we recommend using about 100.

Here is how you can modify the AppWorldLogic.cpp file to create waves in Manual mode:

AppWorldLogic.cpp

Source code (C++)
#include "AppWorldLogic.h"
#include <UnigineWorld.h>

using namespace Unigine;
// World logic, it takes effect only when the world is loaded.
// These methods are called right after corresponding world script's (UnigineScript) methods.

ObjectWaterGlobalPtr water = nullptr;

/* ... */

int AppWorldLogic::init()
{
	// Write here code to be called on world initialization: initialize resources for your world scene during the world start.
	
	water = static_ptr_cast<ObjectWaterGlobal>(World::getNodeByType(Node::OBJECT_WATER_GLOBAL));
	if (!water)
	{
		water = ObjectWaterGlobal::create();
	}
		
	// you can set each wave only in manual mode
	water->setManual(true);

	// add each wave. 
	// addWave(wave length, amplitude, steepness, direction angle[0.0; 360.0], phase offset[0.0; 2*PI])

	water->addWave(8.0, 0.05, 2.0, 270.0, 0.0);
	water->addWave(8.0, 0.015, 1.0, 150.0, 1.0);
	water->addWave(8.0, 0.02, 6.0, 75.0, 0.0);
	water->addWave(16.0, 0.05, 2.0, 270.0, 3.0);
	water->addWave(16.0, 0.05, 7.0, 45.0, 0.5);
	water->addWave(32.0, 0.1, 2.0, 120.0, 2.0);
	water->addWave(64.0, 0.2, 1.0, -90.0, 0.1);

	// change amplitude and length for the second wave 
	water->setWaveAmplitude(1, 0.03);
	water->setWaveLength(1, 10);
	
	return 1;
			
		/* ... */
		
}

See Also#

A UnigineScript API sample <UnigineSDK>/data/samples/objects/water_00

ObjectWaterGlobal Class

Members


static ObjectWaterGlobalPtr create ( ) #

Constructor. Creates a new global water object.

float getHeight ( const Math::Vec3 & position ) const#

Returns a height offset of a given point relatively to the water surface.

Arguments

  • const Math::Vec3 & position - Point position coordinates.

Return value

Height offset of the point.

Math::vec3 getNormal ( const Math::Vec3 & position ) const#

Returns a normal vector of a given point (to orient objects along the waves normals).

Arguments

  • const Math::Vec3 & position - Normal vector.

Return value

Normal vector.

int getPhysicsFieldMask ( ) const#

Returns the FieldHeight physics mask of the assigned material on the Global Water.

Return value

The FieldHeight physics mask.

int getVisualFieldMask ( ) const#

Returns the FieldHeight visual mask of the assigned material on the Global Water.

Return value

The FieldHeight visual mask.

int isWaterFieldHeightInteraction ( ) const#

Checks if the assigned material on the Global Water object has enabled FieldHeight interaction option.

Return value

1 if the FieldHeight interaction option is enabled, otherwise, 0.

float getWaterLevel ( ) const#

Returns the average Z coordinate of the water object.

Return value

The Z coordinate value.

float getWaterLevelMax ( ) const#

Returns the maximum Z coordinate of the water object.

Return value

The Z coordinate value.

float getWaterLevelMin ( ) const#

Returns the minimum Z coordinate of the water object.

Return value

The Z coordinate value.

float getWaterProceduralLevelMax ( const Math::Vec3 & position ) const#

Returns the maximum Z coordinate value of the water object including bounds of additional fields of other objects that affected Global Water heights in a given position.

Arguments

  • const Math::Vec3 & position - A position vector of additional fields.

float getWaterProceduralLevelMin ( const Math::Vec3 & position ) const#

Returns the minimum Z coordinate value of the water object including bounds of additional fields of other objects that affected Global Water heights in a given position.

Arguments

  • const Math::Vec3 & position - A position vector of additional fields.

void setWaterTime ( float time ) #

Sets water time value for water synchronization. It is used for effects, such as normals, caustics, and foam.

Arguments

  • float time - Water time value.

float getWaterTime ( ) const#

Returns water time value for water synchronization.

Return value

Water time value.

void setLayerMaxFadeDistance ( int layer, float distance ) #

Sets the maximum fade-out distance of the layer. It is counted starting from the maximum visibility distance.

Arguments

  • int layer - Layer number
  • float distance - Maximum fade-out distance, in units. If a negative value is provided, 0 will be used instead. The default value is 0.

float getLayerMaxFadeDistance ( int layer ) const#

Returns the maximum fade-out distance of the layer. It is counted starting from the maximum visibility distance.

Arguments

  • int layer - Layer number

Return value

Maximum fade-out distance, in units.

void setLayerMinFadeDistance ( int layer, float distance ) #

Sets the minimum fade-in distance of the layer. It is counted starting from the minimum visibility distance.

Arguments

  • int layer - Layer number
  • float distance - Minimum fade-in distance, in units. If a negative value is provided, 0 will be used instead. The default value is 0.

float getLayerMinFadeDistance ( int layer ) const#

Returns the minimum fade-in distance of the layer. It is counted starting from the minimum visibility distance.

Arguments

  • int layer - Layer number

Return value

Minimum fade-in distance, in units.

void setLayerMaxVisibleDistance ( int layer, float distance ) #

Sets the maximum visibility distance of the layer. It is the distance, starting from which the layer begins to fade out until it becomes completely invisible.

Arguments

  • int layer - Layer number
  • float distance - Maximum visibility distance, in units. If a negative value is provided, 0 will be used instead. The default value is inf.

float getLayerMaxVisibleDistance ( int layer ) const#

Returns the maximum visibility distance of the layer. It is the distance, starting from which the layer begins to fade out until it becomes completely invisible.

Arguments

  • int layer - Layer number

Return value

Maximum visibility distance, in units.

void setLayerMinVisibleDistance ( int layer, float distance ) #

Sets the minimum visibility distance of the layer. It is the distance, starting from which the layer begins to fade in until it becomes completely visible.

Arguments

  • int layer - Layer number
  • float distance - Minimum visibility distance, in units. If a negative value is provided, 0 will be used instead. The default value is -inf.

float getLayerMinVisibleDistance ( int layer ) const#

Returns the minimum visibility distance of the layer. It is the distance, starting from which the layer begins to fade in until it becomes completely visible.

Arguments

  • int layer - Layer number

Return value

Minimum visibility distance, in units.

void setLayerName ( int layer, cstr name ) #

Sets a new name for the layer.

Arguments

  • int layer - Layer number
  • cstr name - Name of the layer.

cstr getLayerName ( int layer ) const#

Returns the name of the layer.

Arguments

  • int layer - Layer number

Return value

Name of the layer

void setLayerWeight ( int layer, float weight ) #

Sets a weight for a given layer.

Arguments

  • int layer - Layer number
  • float weight - Layer weight

float getLayerWeight ( int layer ) const#

Returns the weight of the layer.

Arguments

  • int layer - Layer number

Return value

Weight of the layer.

void setLayerDirectionAngleVariance ( int layer, float variance ) #

Sets a variance value of the wave direction angle for a given layer.

Arguments

  • int layer - Layer number
  • float variance - Variance value.

float getLayerDirectionAngleVariance ( int layer ) const#

Returns the current variance value of the wave direction angle for a given layer.

Arguments

  • int layer - Layer number

Return value

Variance value.

void setLayerSteepnessScale ( int layer, float steepness_scale ) #

Sets a steepness scale value for a given layer.

Arguments

  • int layer - Layer number
  • float steepness_scale - Steepness scale value.

float getLayerSteepnessScale ( int layer ) const#

Returns the current steepness scale value for a given layer.

Arguments

  • int layer - Layer number

Return value

Steepness scale value.

void setLayerAmplitudeRange ( int layer, vec2 range ) #

Sets a range of wave amplitudes for a given layer.

Arguments

  • int layer - Layer number.
  • vec2 range - Amplitude range.

vec2 getLayerAmplitudeRange ( int layer ) const#

Returns the current range of wave amplitudes of a given layer.

Arguments

  • int layer - Layer number.

Return value

Amplitude range.

void setLayerLengthRange ( int layer, vec2 range ) #

Sets a range of wave lengths for a given layer.

Arguments

  • int layer - Layer number
  • vec2 range - Length range.

vec2 getLayerLengthRange ( int layer ) const#

Returns the current range of wave lengths of a given layer.

Arguments

  • int layer - Layer number

Return value

Length range.

void setLayerNumWaves ( int layer, int num ) #

Sets the number of waves for a given layer.

Arguments

  • int layer - Layer number
  • int num - Number of waves.

int getLayerNumWaves ( int layer ) const#

Returns the number of waves of a given layer.

Arguments

  • int layer - Layer number

Return value

Number of waves.

int isLayerEnabled ( int layer ) const#

Returns a value indicating if a given layer is enabled.

Arguments

  • int layer - Layer number

Return value

1 if the layer is disabled; otherwise, 0.

void setLayerEnabled ( int layer, int enabled ) #

Enables or disables a given layer.

Arguments

  • int layer - Layer number
  • int enabled - 1 to enable the layer, 0 to disable it.

void swapLayer ( int layer1, int layer2 ) #

Swaps two specified layers.

Arguments

  • int layer1 - Layer1 number.
  • int layer2 - Layer2 number.

int getNumLayers ( ) const#

Returns the current number of layers.

Return value

Number of layers.

void removeLayer ( int layer ) #

Removes a given layer.

Arguments

  • int layer - Layer number

int addLayer ( ) #

Appends a new layer.

Return value

Number of the new added layer.

void setWavePhaseOffset ( int num, float offset ) #

Sets the phase offset parameter for a given wave.

Arguments

  • int num - Wave number.
  • float offset - Phase offset parameter value in radians in range [0; 2pi].

float getWavePhaseOffset ( int num ) const#

Returns the value of the Phase Offset parameter of a wave.

Arguments

  • int num - Wave number.

Return value

Phase offset parameter value in radians in range [0; 2pi].

void setWaveDirectionAngle ( int num, float angle ) #

Sets direction (angle of spreading) for a given wave:
  • If 0 is specified, the wave spreads along the Y axis and is parallel to the X axis.
  • If a positive value is specified, the wave direction is slanted counterclockwise relative to its initial spread.
  • If a negative value is specified, the wave is rotated clockwise.

Arguments

  • int num - Wave number.
  • float angle - Angle, in degrees. Both positive and negative values are acceptable.

float getWaveDirectionAngle ( int num ) const#

Returns direction (angle of spreading) of a given wave.

Arguments

  • int num - Wave number.

Return value

Angle, in degrees.

void setWaveSteepness ( int num, float steepness ) #

Sets the steepness value for a given wave.

Arguments

  • int num - Wave number.
  • float steepness - Steepness value.

float getWaveSteepness ( int num ) const#

Returns the current steepness value of the given wave.

Arguments

  • int num - Wave number.

Return value

Steepness value.

void setWaveAmplitude ( int num, float amplitude ) #

Sets the distance between the highest and the lowest peaks for the given wave. It sets the wave form along with the setWaveLength() function. The higher the value is, the higher the waves are.

Arguments

  • int num - Wave number.
  • float amplitude - Amplitude, in units.

float getWaveAmplitude ( int num ) const#

Returns the distance between the highest and the lowest peaks for the given wave.

Arguments

  • int num - Wave number.

Return value

Amplitude, in units.

void setWaveLength ( int num, float length ) #

Sets the distance between successive crests for the given wave. The higher the length value is, the broader the waves are.

Arguments

  • int num - Wave number.
  • float length - Length, in units.

float getWaveLength ( int num ) const#

Returns the distance between successive crests of the given wave.

Arguments

  • int num - Wave number.

Return value

Length, in units.

int getNumWaves ( ) const#

Returns the current number of the simulated waves.

Return value

Number of waves.

void removeWave ( int num ) #

Removes the wave having a specified number.

Arguments

  • int num - Wave number.

int addWave ( float length , float amplitude, float steepness, float direction_angle, float phase ) #

Adds a wave if the manual mode is enabled.

Arguments

  • float length - Wave length.
  • float amplitude - Wave amplitude.
  • float steepness - Wave steepness.
  • float direction_angle - Angle of the wave direction in degrees. At 0 angle the wave will be directed along the X-axis.
  • float phase - Phase offset of the wave in radians (0 to 2pi).

Return value

Number of the added wave.

int isManual ( ) const#

Returns a value indicating if the manual mode is enabled. In this mode you create your own waves and have full control over them. Layers are not functional in this mode.

Return value

1 if the manual mode is set; otherwise, 0.

void setManual ( int enabled ) #

Enables or disables the manual mode. In this mode you create your own waves and have full control over them. Layers are not functional in this mode.

Arguments

  • int enabled - 1 to enable the manual mode, 0 to disable the manual mode.

int isWaterFieldShorelineInteraction ( ) const#

Checks if the assigned material on the Global Water object has enabled FieldShoreline interaction option.

Return value

1 if the FieldShoreline interaction option is enabled, otherwise, 0.

int getIntersectionQuality ( ) const#

Returns the current number of iterations used in intersection calculations.

Return value

Number of iterations (0 to 4).

void setIntersectionQuality ( int num ) const#

Sets the number of iterations used in intersection calculations. A larger number of iterations gives a more precise result, but affects performance.

Arguments

  • int num - Number of iterations (0 to 4). The default number is 0

float getIntersectionAmplitudeThreshold ( ) const#

Returns the current threshold of amplitude values that will not participate in intersection calculations.

Return value

Amplitude threshold.

void setIntersectionAmplitudeThreshold ( float threshold ) #

Sets the threshold for amplitude values that will not participate in intersection calculations. The default value is 0.1f.

Arguments

  • float threshold - Amplitude threshold.

float getIntersectionAccuracy ( ) const#

Returns current intersection accuracy which represents an error between the real value of the water intersection point and the calculated value.

Return value

Accuracy value.

void setIntersectionAccuracy ( float accuracy ) #

Sets an intersection accuracy which represents an error between the real value of the water intersection point and the calculated value. The default value is 0.25.

Arguments

  • float accuracy - Accuracy value.

int getHeightQuality ( ) const#

Returns the current number of iterations used to calculate the height value.

Return value

Number of iterations (0 to 4).

void setHeightQuality ( int num ) #

Sets the number of iterations used to calculate the height value. A larger number of iterations gives a more precise height value, but affects performance.

Arguments

  • int num - Number of iterations (0 to 4). The default number is 0.

float getHeightAmplitudeThreshold ( ) const#

Returns the current threshold for amplitude values that will not participate in height calculations.

Return value

Amplitude threshold.

void setHeightAmplitudeThreshold ( float threshold ) #

Sets the threshold for amplitude values that will not participate in height calculations. The more you cut off, the less accurate the height value you get, but the faster are the calculations.

Arguments

  • float threshold - Amplitude threshold. The default value is 0.1f.

float getWindAffect ( ) const#

Returns the current value determining how much the wind direction affects the waves.

Return value

Wind influence value in range [0;1].

void setWindAffect ( float value ) #

Sets how much the wind direction affects the waves.

Arguments

  • float value - Wind influence in range [0;1]. If you set it to 1, all waves will be directed along the wind direction.

float getWindDirectionAngle ( ) const#

Returns the angle that determines the wind direction.

Return value

Angle, in degrees.

void setWindDirectionAngle ( float angle ) #

Sets the angle that determines the wind direction.

Arguments

  • float angle - Wind direction angle, in degrees.

int type ( ) const#

Returns the type of the node.

Return value

Object type identifier.
Last update: 2021-09-29
Build: ()