<br />
<b>Warning</b>:  Undefined array key "translationlc" in <b>/usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php</b> on line <b>237</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
<br />
<b>Warning</b>:  Cannot modify header information - headers already sent by (output started at /usr/www/users/fabook/_diggets/doc/v2/lib/plugins/translation/action.php:237) in <b>/usr/www/users/fabook/_diggets/doc/v2/inc/Action/Export.php</b> on line <b>104</b><br />
====== Water ======

A water surface is not seldomly a popular game component. We do not provide directly a water surface component, but it is quite easy to setup one.

{{ :water-example.jpg |}}

Water rendering is based on:
  * a plane
  * refraction computation
  * reflection computation
  * and the water shader itself
===== Components =====

==== Plane ====

The plane is a simple and opaque instance of TGorillaPlane or TPlane. It will be used as basis mesh to render water onto.

==== Refraction ====

Refraction is the image data simulating __underwater__ 3D objects, modified by some visual effects (Fresnel Effect). We'll need a separated RenderPass for this, to pre-compute the information.
That's the reason why there is no all-in-one component for water, because we want users to reuse their renderpasses instead of instanciating multiple renderpasses for the same image data. This would lead to horrible performance issues. It means you could use the refraction renderpass for water and at the same time f.e. for some transparency effect.

Create an instance of TGorillaRenderPassRefraction and apply the viewport and camera to it.

Because we don't want to appear the water surface itself (would be black) in this image data, we should ignore it while refraction computation. This can be done very easily, by:
<file pascal>
FRefraction.IgnoreControl(FWaterPlane);
</file>
The water surface would be black, because it's image information will be computed in main render pass first.

==== Reflection ====

Reflection is the image data containing a mirrored view on the scene depending on the current camera position and direction. As the name already says, it will be displayed as 3D object reflection on the water surface.

Create an instance of TGorillaRenderPassReflection and apply the viewport and camera to it.

And again we'll need to ignore the water plane while computation, by:
<file pascal>
FReflection.IgnoreControl(FWaterPlane);
</file>

Because the reflection pass always computes the mirrored camera view, we should tell him, how the virtual mirror surface looks like:
<file pascal>
  // for plane vector computation we need to know the size of this mirror plane
  FReflection.MirrorSize := FWaterPlane.Width;
  
  // set the current position of the water plane as mirror plane
  // this needs to be updated, if water plane moves
  FReflection.MirrorPosition := TPoint3D(FWaterPlane.AbsolutePosition);
</file>

In case plane size or position changes, you have to update those values in reflection pass.

==== Water Material ====

Finally of course we need a material shader (TGorillaWaterMaterialSource), which is able to merge all components together. The material source is inherited from the TGorillaDefaultMaterialSource and supports multiple light sources and the different shading models.

For computing waves, riffles and foam the shader needs a few textures:
  * NormalTexture
  * DUDVTexture
  * DisplacementTexture
  * SpeculareTexture
  * FoamTexture

The different textures may look like these:

{{:water-normal.jpg?200|Water normals map}}
{{:water-dudv.jpg?200|Water DUDV map}}
{{:water-height.jpg?200|Water displacement map}}
{{:water-height.jpg?200|Water specular map}}
{{:water-foam.jpg?200|Water foam texture}}

**Attention: The image source is unknown! It is not advisable to use these images and, if necessary, to violate the license agreement.**

After loading all relevant textures to material source, we only have to apply refraction and reflection to it:
<file pascal>
  FWaterMaterial.ReflectionPass := FReflection;
  FWaterMaterial.RefractionPass := FRefraction;
</file>

__Remarks:__ normal map texture will also be used as displacement map for simulating real mesh waves, in case no explicit displacement map was applied to the material.

In the end do not forget to link water plane with water material source.
<file pascal>
FWaterPlane.MaterialSource := FWaterMaterial;
</file>

=== Properties ===

Besides the textures, the water material source provides a few configuration properties to influence water look.

^ Property ^ Description ^
| Diffuse | The material shader uses this color as main color for water. |
| Specular | The specular color interacts with the applied specular color map and configurates its intensity. |
| WaveSpeed | Defines how fast waves are moving. |
| WaveSize | Defines the amplitude of waves, which means how high or low waves are simulated. This value do not manipulate mesh vertices (only by displacement mapping). |
| Displacement | Defines the factor of vertex displacement based on the displacement map or normal map. |
| ReflCorrection | By this value you can modify the color of reflection, default value: Vector3D(1.0, 1.0, 1.0, 1.0) |
| RefrCorrection | By this value you can modify the color of refraction on water surface, default value: Vector3D(1.1, 1.1, 1.1, 1.0) |

==== Ripples ====

Since 0.8.3.2265 the framwork supports rendering of water ripples.

Ripple settings are configurable at design time by the following properties, but need runtime implementation to add ripple positions.

^Property^Description^
|RipplesActive|Activate or deactivate ripple computation.|
|RippleAmplification|Get or set amplification value for ripples. Simply said: Amplification describes the height of the ripple.|
|RippleProximity|Get or set proximity value for ripples. Simply said: Proximity is the basis value for the width of a ripple.|
|RippleDecay|Get or set decay value for ripples. Simply said: It defines how fast a ripple will end.|

To add a ripple at a certain position use the TGorillaWaterMaterialSource.AddRipple() method.

__Warning:__ The number of ripples is currently hardcoded limited to 32.

<file pascal>
procedure TForm1.doOnViewportMouseUp(ASender : TObject; AButton : TMouseButton;
  AShift : TShiftState; X, Y : Single);
var LPt3D : TPoint3D;
begin
  /// add a ripple by clicking with the left mouse button onto the water plane (Caution: HitTest needs to be activated)
  if (ssLeft in fShiftState) then
  begin
    LPt3D := GorillaViewport1.ScreenToWorld(PointF(X, Y));
    GorillaWaterMaterialSource1.AddRipple(Point3D(LPt3D.X, LPt3D.Z, -LPt3D.Y));
  end;
end;
</file>
===== Example =====

{{youtube>HGlyOlVD28I?medium}}

Take a look at this example code for a complex water surface setup.

<file pascal>
procedure TForm1.CreateWater(const AAssetsPath : String);
var LTexPath : String;
begin
  LTexPath := IncludeTrailingPathDelimiter(AAssetsPath + 'water');

  /// create the water plane
  FWaterPlane := TGorillaPlane.Create(FViewport);
  FWaterPlane.Name := 'WaterPlane1';
  FWaterPlane.BeginUpdate();
  try
    FWaterPlane.Parent := FViewport;
    FWaterPlane.HitTest := false;
    FWaterPlane.RotationAngle.X := -90;
    FWaterPlane.Width  := MAP_SIZE;
    FWaterPlane.Height := MAP_SIZE;
    FWaterPlane.Depth  := 1;
    FWaterPlane.SubdivisionsHeight := 64;
    FWaterPlane.SubdivisionsWidth  := 64;
    FWaterPlane.Position.Y := -25;
  finally
    FWaterPlane.EndUpdate();
  end;

  /// create reflection render pass for water material
  FReflection := TGorillaRenderPassReflection.Create(FViewport);
  FReflection.Viewport := FViewport;
  FReflection.Camera := FCamera;
  FReflection.IgnoreControl(FWaterPlane);
  FReflection.MirrorSize := FWaterPlane.Width;
  
  // set the current position of the water plane as mirror plane
  // this needs to be updated, if water plane moves
  FReflection.MirrorPosition := TPoint3D(FWaterPlane.AbsolutePosition);
  FReflection.Enabled := true;

  /// create refraction render pass for water material
  FRefraction := TGorillaRenderPassRefraction.Create(FViewport);
  FRefraction.Viewport := FViewport;
  FRefraction.IgnoreControl(FWaterPlane);
  FRefraction.Enabled := true;

  /// create material source
  FWaterMaterial := TGorillaWaterMaterialSource.Create(FWaterPlane);
  FWaterMaterial.Parent := FWaterPlane;
  FWaterMaterial.NormalMap.LoadFromFile(LTexPath + 'water_normal.png');
  FWaterMaterial.DUDVTexture.LoadFromFile(LTexPath + 'water3-dudv.jpg');
  FWaterMaterial.DisplacementMap.LoadFromFile(LTexPath + 'water_height.png');
  FWaterMaterial.SpecularMap.LoadFromFile(LTexPath + 'water_height.png');
  FWaterMaterial.FoamTexture.LoadFromFile(LTexPath + 'foam.png');

  /// link reflection and refraction render pass to water material
  FWaterMaterial.ReflectionPass := FReflection;
  FWaterMaterial.RefractionPass := FRefraction;

  FWaterPlane.MaterialSource := FWaterMaterial;
end;
</file>

Next step: [[bokeh|Bokeh]]