Water Material

The water material system in Gorilla3D creates realistic water surfaces by combining multiple render passes and texture maps. The TGorillaWaterMaterialSource component provides a comprehensive shader-based water rendering solution with wave animation, reflections, refractions, foam, and interactive ripples.

Overview

Water rendering in Gorilla3D uses a specialized material that combines:

  • DUDV displacement mapping for wave distortion
  • Normal mapping for surface detail
  • Reflection and refraction render passes for realistic light behavior
  • Depth-based effects for shore foam and transparency
  • Specular highlights for sun/light reflections
  • Interactive ripples for dynamic water surfaces

Basic Setup

Required Components

A complete water surface requires:

  1. Mesh: TGorillaPlane or custom water mesh
  2. Material: TGorillaWaterMaterialSource
  3. Reflection Pass: TGorillaRenderPassReflection
  4. Refraction Pass: TGorillaRenderPassRefraction
  5. Depth Pass: Provided by refraction pass or separate depth pass

Minimal Configuration

var
  WaterMaterial: TGorillaWaterMaterialSource;
  WaterPlane: TGorillaPlane;
  ReflectionPass: TGorillaRenderPassReflection;
  RefractionPass: TGorillaRenderPassRefraction;
begin
  // Create water material
  WaterMaterial := TGorillaWaterMaterialSource.Create(Self);
  WaterMaterial.Diffuse := TAlphaColorF.Create(0.1, 0.3, 0.5, 0.8);

  // Load required textures
  WaterMaterial.DUDVTexture.LoadFromFile('water_dudv.png');
  WaterMaterial.NormalMap.LoadFromFile('water_normal.png');
  WaterMaterial.SpecularMap.LoadFromFile('water_spec.png');

  // Configure render passes
  WaterMaterial.Reflections := True;
  WaterMaterial.ReflectionPass := ReflectionPass;
  WaterMaterial.Refractions := True;
  WaterMaterial.RefractionPass := RefractionPass;

  // Create water plane
  WaterPlane := TGorillaPlane.Create(Self);
  WaterPlane.Width := 100.0;
  WaterPlane.Height := 100.0;
  WaterPlane.MaterialSource := WaterMaterial;
end;

Required Textures

DUDV Map (Displacement)

A DUDV map stores directional displacement information, primarily in the Red and Green channels. This texture creates the wave distortion effect.

Characteristics:

  • Red/yellow/green appearance
  • Tileable texture recommended
  • Derived from normal maps
  • Best when slightly blurred

Property: DUDVTexture: TBitmap

Example:

WaterMaterial.DUDVTexture.LoadFromFile('water_dudv.png');

Normal Map

Surface normal information for lighting calculations and wave detail.

Characteristics:

  • Standard RGB normal map
  • Should match DUDV distortion patterns
  • Blue-dominant appearance

Property: NormalMap: TBitmap

Example:

WaterMaterial.NormalMap.LoadFromFile('water_normal.png');

Specular Map

Controls specular highlight intensity across the water surface.

Characteristics:

  • Grayscale or RGB
  • White = strong highlights, Black = weak highlights
  • Can be procedural or texture-based

Property: SpecularMap: TBitmap

Example:

WaterMaterial.SpecularMap.LoadFromFile('water_spec.png');

Displacement Map (Optional)

Vertex displacement for actual geometry deformation (wave height).

Characteristics:

  • Grayscale height map
  • Affects vertex positions in vertex shader
  • Performance cost for high polygon meshes

Properties:

  • DisplacementMap: TBitmap
  • Displacement: TVector3D - Direction vector
  • DisplIntensity: Single - Displacement strength (0.0-100.0)

Example:

WaterMaterial.DisplacementMap.LoadFromFile('water_height.png');
WaterMaterial.Displacement := Vector3D(0, 1, 0);  // Y-axis displacement
WaterMaterial.DisplIntensity := 0.5;

Foam Texture (Optional)

Surface foam overlay texture.

Property: FoamTexture: TBitmap

Related Properties:

  • FoamDirection: TPointF - Foam movement direction
  • FoamIntensity: Single - Foam visibility (0.0-10.0)

Example:

WaterMaterial.FoamTexture.LoadFromFile('foam.png');
WaterMaterial.FoamDirection := PointF(0.5, 0.5);
WaterMaterial.FoamIntensity := 1.0;

Shore Texture (Optional)

Shore foam texture displayed at shallow water edges.

Property: ShoreTexture: TBitmap

Related Properties:

  • ShoreWidth: Single - Shore effect range (0.0001-100.0)
  • ShoreIntensity: Single - Shore foam brightness (0.0-10.0)

Example:

WaterMaterial.ShoreTexture.LoadFromFile('shore_foam.png');
WaterMaterial.ShoreWidth := 2.0;
WaterMaterial.ShoreIntensity := 3.0;

Material Properties

Wave Animation

Property Type Default Range Description
WaveSpeed Single 1.0 0.0+ Animation speed multiplier. Higher = faster wave movement.
WaveSize Single 1.0 0.0+ Wave distortion strength/amplitude.

Example:

WaterMaterial.WaveSpeed := 0.8;  // Slower waves
WaterMaterial.WaveSize := 1.5;   // Larger waves

Color and Appearance

Property Type Description
Diffuse TAlphaColorF Base water color (RGB + transparency).
DiffusePower Single Mix ratio between diffuse color and refraction.
Specular TAlphaColorF Specular highlight color.
Shininess Single Specular sharpness (higher = sharper highlights).

Example:

WaterMaterial.Diffuse := TAlphaColorF.Create(0.05, 0.2, 0.4, 0.7);
WaterMaterial.DiffusePower := 1.0;
WaterMaterial.Specular := TAlphaColorF.Create(1.0, 1.0, 1.0, 1.0);
WaterMaterial.Shininess := 128.0;

Depth Effects

Property Type Range Description
DepthIntensity Single 0.001-10.0 Depth map influence on transparency and effects.

Controls how depth information affects water appearance. Lower values = more transparent deep water, higher values = more opaque deep water.

Example:

WaterMaterial.DepthIntensity := 1.5;

Reflection and Refraction

Property Type Range Description
Reflections Boolean - Enable reflection mapping.
ReflectionPass TGorillaRenderPassController - Linked reflection render pass.
ReflectionPower Single 0.0-1.0 Reflection intensity.
ReflCorrection TVector3D - RGB color correction for reflections.
Refractions Boolean - Enable refraction mapping.
RefractionPass TGorillaRenderPassController - Linked refraction render pass.
RefractionPower Single 0.0-1.0 Refraction intensity.
RefrCorrection TVector3D - RGB color correction for refractions.

Example:

// Reflection setup
WaterMaterial.Reflections := True;
WaterMaterial.ReflectionPass := ReflectionPass;
WaterMaterial.ReflectionPower := 0.6;
WaterMaterial.ReflCorrection := Vector3D(1.0, 1.0, 1.0);

// Refraction setup
WaterMaterial.Refractions := True;
WaterMaterial.RefractionPass := RefractionPass;
WaterMaterial.RefractionPower := 0.8;
WaterMaterial.RefrCorrection := Vector3D(1.0, 1.0, 1.1);  // Slight blue tint

Debug Output Layers

The OutputLayer property allows visualization of individual shader components for debugging.

Value Description
wolAll Normal rendering (all layers combined).
wolDUDV Show DUDV displacement map only.
wolNormal Show normal map only.
wolSpecular Show specular highlights only.
wolFoam Show foam layer only.
wolDepth Show depth map visualization.
wolRefraction Show refraction pass only.
wolReflection Show reflection pass only.
wolReflPlusRefr Show reflection + refraction blend.
wolTexCoords Show texture coordinates.

Example:

WaterMaterial.OutputLayer := wolDepth;  // Debug depth mapping

Ripples System

Interactive ripples were introduced in v0.8.3.2265 for dynamic water surface disturbances.

Configuration

Property Type Description
RipplesActive Boolean Enable/disable ripple computation.
RippleAmplification Single Ripple height/amplitude.
RippleProximity Single Ripple width (basis value).
RippleDecay Single Fade-out speed.

Adding Ripples

procedure AddRipple(APos: TVector3D); overload;
procedure AddRipple(APos: TPoint3D); overload;
procedure AddRipples(const AArr: TArray<TVector3D>);
procedure SetRipples(const AArr: TArray<TVector3D>);
procedure ClearRipples();

Limitations:

  • Maximum 32 simultaneous ripples (platform-dependent)
  • Oldest ripples removed when limit exceeded

Example:

// Enable ripples
WaterMaterial.RipplesActive := True;
WaterMaterial.RippleAmplification := 0.5;
WaterMaterial.RippleProximity := 2.0;
WaterMaterial.RippleDecay := 0.95;

// Add ripple at world position
WaterMaterial.AddRipple(Point3D(10.0, 0.0, 5.0));

// Add multiple ripples
var Positions: TArray<TVector3D>;
SetLength(Positions, 3);
Positions[0] := Vector3D(0, 0, 0);
Positions[1] := Vector3D(5, 0, 5);
Positions[2] := Vector3D(-5, 0, 5);
WaterMaterial.AddRipples(Positions);

// Clear all ripples
WaterMaterial.ClearRipples();

Render Pass Configuration

Reflection Pass Setup

The reflection pass must exclude the water plane to prevent self-reflection artifacts.

var
  ReflectionPass: TGorillaRenderPassReflection;
begin
  ReflectionPass := TGorillaRenderPassReflection.Create(Self);
  ReflectionPass.Viewport := Viewport;
  ReflectionPass.Camera := Camera;

  // Exclude water plane from reflection
  ReflectionPass.IgnoreControl(WaterPlane);

  // Configure reflection plane
  ReflectionPass.MirrorPosition.Point := TPoint3D(WaterPlane.AbsolutePosition);
  ReflectionPass.MirrorSize := WaterPlane.Width;
end;

Refraction Pass Setup

The refraction pass provides both underwater color and depth information.

var
  RefractionPass: TGorillaRenderPassRefraction;
begin
  RefractionPass := TGorillaRenderPassRefraction.Create(Self);
  RefractionPass.Viewport := Viewport;

  // Exclude water plane from refraction
  RefractionPass.IgnoreControl(WaterPlane);

  // Configure refraction plane
  RefractionPass.SurfacePosition.Point := TPoint3D(WaterPlane.AbsolutePosition);
end;

Displacement Offset Compensation

When using displacement mapping, the water plane's visual position shifts. Adjust render pass planes to compensate:

ReflectionPass.MirrorPosition.Point := TPoint3D(FWaterPlane.AbsolutePosition) + Point3D(0, -WaterMaterial.DisplIntensity, 0);

RefractionPass.SurfacePosition.Point := TPoint3D(FWaterPlane.AbsolutePosition) + Point3D(0, -WaterMaterial.DisplIntensity, 0);

Complete Example

procedure TForm1.CreateWaterScene;
var
  WaterMaterial: TGorillaWaterMaterialSource;
  WaterPlane: TGorillaPlane;
  ReflectionPass: TGorillaRenderPassReflection;
  RefractionPass: TGorillaRenderPassRefraction;
begin
  // Create render passes
  ReflectionPass := TGorillaRenderPassReflection.Create(Self);
  ReflectionPass.Viewport := Viewport;
  ReflectionPass.Camera := Camera;

  RefractionPass := TGorillaRenderPassRefraction.Create(Self);
  RefractionPass.Viewport := Viewport;

  // Create water material
  WaterMaterial := TGorillaWaterMaterialSource.Create(Viewport);

  // Basic appearance
  WaterMaterial.Diffuse := TAlphaColorF.Create(0.1, 0.25, 0.4, 0.75);
  WaterMaterial.Specular := TAlphaColorF.Create(1.0, 1.0, 1.0, 1.0);
  WaterMaterial.Shininess := 128.0;

  // Load textures
  WaterMaterial.DUDVTexture.LoadFromFile('textures\water_dudv.png');
  WaterMaterial.NormalMap.LoadFromFile('textures\water_normal.png');
  WaterMaterial.SpecularMap.LoadFromFile('textures\water_spec.png');
  WaterMaterial.FoamTexture.LoadFromFile('textures\foam.png');
  WaterMaterial.ShoreTexture.LoadFromFile('textures\shore_foam.png');

  // Wave animation
  WaterMaterial.WaveSpeed := 0.5;
  WaterMaterial.WaveSize := 1.2;

  // Foam configuration
  WaterMaterial.FoamDirection := PointF(0.3, 0.7);
  WaterMaterial.FoamIntensity := 1.5;
  WaterMaterial.ShoreWidth := 3.0;
  WaterMaterial.ShoreIntensity := 2.5;

  // Depth and transparency
  WaterMaterial.DepthIntensity := 1.8;
  WaterMaterial.DiffusePower := 1.0;

  // Reflection setup
  WaterMaterial.Reflections := True;
  WaterMaterial.ReflectionPass := ReflectionPass;
  WaterMaterial.ReflectionPower := 0.5;
  WaterMaterial.ReflCorrection := Vector3D(1.0, 1.0, 1.0);

  // Refraction setup
  WaterMaterial.Refractions := True;
  WaterMaterial.RefractionPass := RefractionPass;
  WaterMaterial.RefractionPower := 0.8;
  WaterMaterial.RefrCorrection := Vector3D(1.0, 1.0, 1.15);

  // Ripples
  WaterMaterial.RipplesActive := True;
  WaterMaterial.RippleAmplification := 0.4;
  WaterMaterial.RippleProximity := 2.5;
  WaterMaterial.RippleDecay := 0.92;

  // Create water plane
  WaterPlane := TGorillaPlane.Create(Self);
  WaterPlane.Width := 100.0;
  WaterPlane.Height := 100.0;
  WaterPlane.SubdivisionsWidth := 64;
  WaterPlane.SubdivisionsHeight := 64;
  WaterPlane.MaterialSource := WaterMaterial;

  // Exclude water from render passes
  ReflectionPass.IgnoreControl(WaterPlane);
  RefractionPass.IgnoreControl(WaterPlane);
end;

procedure TForm1.OnWaterPlaneMouseClick(ASender: TObject; 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;

Performance Considerations

  1. Subdivision Density: Higher mesh subdivision improves displacement mapping but increases vertex processing cost.

  2. Render Pass Resolution: Lower resolution reflection/refraction textures improve performance significantly.

  3. Ripple Count: Each active ripple adds computation cost. Limit simultaneous ripples for best performance.

  4. Texture Sizes: Use power-of-two textures (256x256, 512x512) for optimal GPU performance.

  5. Platform Differences: Mobile platforms have lower limits regarding texture performance.

Troubleshooting

Water Appears Black or Incorrect

Cause: Missing or incorrectly configured render passes.

Solution:

  • Verify Reflections and Refractions are enabled
  • Check ReflectionPass and RefractionPass are assigned
  • Ensure render passes exclude the water plane by IgnoreControl()

Reflections/Refractions Show Water Surface

Cause: Water plane not excluded from render passes.

Solution:

ReflectionPass.IgnoreControl(WaterPlane);
RefractionPass.IgnoreControl(WaterPlane);

Ripples Not Visible

Cause: RipplesActive is false or ripple parameters too subtle.

Solution:

WaterMaterial.RipplesActive := True;
WaterMaterial.RippleAmplification := 1.0;  // Increase for visibility

Displacement Offset Issues

Cause: Render pass planes don't account for displacement offset.

Solution: Adjust reflection/refraction plane positions by displacement amount.

See Also