Gorilla.Material.Water Unit Reference

Overview

The Gorilla.Material.Water unit provides the water material system for Gorilla3D, implementing realistic water rendering through specialized shader programs. This unit includes the TGorillaWaterMaterialSource component and the internal TGorillaWaterMaterial class, which together create animated water surfaces with reflections, refractions, foam, depth effects, and interactive ripples.

Architecture

The water material extends the default material system with specialized shader nodes:

TGorillaWaterMaterialSource (Component)
└─ TGorillaWaterMaterial (Internal Material)
   ├─ Vertex Shader (with displacement)
   ├─ Fragment Shader (water surface computation)
   ├─ Texture Pool (DUDV, foam, shore, specular, normal, displacement)
   └─ Uniform Buffers (water parameters, ripples)

Core Classes

TGorillaWaterMaterialSource

Primary water material source component for design-time and runtime configuration.

Inheritance: TGorillaDefaultMaterialSource → TGorillaWaterMaterialSource

Platforms: All Gorilla3D supported platforms

Version: Available since v0.8.3+

Published Properties

Wave Animation
Property Type Default Description
WaveSpeed Single 1.0 Wave animation speed multiplier. Higher values = faster wave movement over DUDV texture.
WaveSize Single 1.0 Wave distortion amplitude. Higher values = stronger displacement effect.

Color Properties
Property Type Description
Diffuse TAlphaColorF Base water color (RGB + alpha transparency). Inherited from TGorillaDefaultMaterialSource.
Specular TAlphaColorF Specular highlight color. Inherited from TGorillaDefaultMaterialSource.
Ambient TAlphaColorF Ambient color contribution. Inherited from TGorillaDefaultMaterialSource.
Emissive TAlphaColorF Self-illumination color. Inherited from TGorillaDefaultMaterialSource.
Shininess Single Specular shininess exponent (higher = sharper highlights). Inherited from TGorillaDefaultMaterialSource.
DiffusePower Single Mix ratio between diffuse color and refraction channel.

Foam Configuration
Property Type Default Description
FoamTexture TBitmap - Foam overlay texture displayed on water surface.
FoamDirection TPointF (0, 0) Foam movement direction vector (normalized). Stored as FoamDirectionVector in DFM.
FoamIntensity Single 0.0 Foam color intensity multiplier (0.0-10.0).

Shore Foam Configuration
Property Type Range Description
ShoreTexture TBitmap - Shore foam texture displayed at shallow water edges.
ShoreWidth Single 0.0001-100.0 Shore effect range. Calculation: pow(water_depth, shore_width).
ShoreIntensity Single 0.0-10.0 Shore foam brightness multiplier.

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

Displacement Mapping
Property Type Description
DisplacementMap TBitmap Height map texture for vertex displacement.
Displacement TVector3D Displacement direction vector (typically (0,1,0) for Y-axis). Stored as DisplacementVector in DFM.
DisplIntensity Single Displacement strength multiplier (0.0-100.0).

Texture Maps
Property Type Description
DUDVTexture TBitmap DUDV displacement map (red/green channels for distortion).
NormalMap TBitmap Normal map for surface detail and lighting.
SpecularMap TBitmap Specular intensity map (controls highlight strength).

Reflection Configuration
Property Type Range Description
Reflections Boolean - Enable reflection mapping.
ReflectionPass TGorillaRenderPassController - Linked reflection render pass.
ReflectionPower Single 0.0-1.0 Reflection intensity multiplier.
ReflCorrection TVector3D - RGB color correction for reflection channel. Stored as ReflCorrectionVector in DFM.

Refraction Configuration
Property Type Range Description
Refractions Boolean - Enable refraction mapping.
RefractionPass TGorillaRenderPassController - Linked refraction render pass.
RefractionPower Single 0.0-1.0 Refraction intensity multiplier.
RefrCorrection TVector3D - RGB color correction for refraction channel. Stored as RefrCorrectionVector in DFM.

Ripples System (v0.8.3.2265+)
Property Type Description
RipplesActive Boolean Enable/disable ripple computation.
RippleAmplification Single Ripple height/amplitude.
RippleProximity Single Ripple width (basis value for ripple spread).
RippleDecay Single Ripple fade-out speed (0.0-1.0, higher = slower decay).

Debug and Advanced
Property Type Description
OutputLayer TWaterOutputLayer Debug visualization mode (see TWaterOutputLayer enum).
Tonemapping TGorillaTonemapping Tonemapping operator. Inherited from TGorillaDefaultMaterialSource.
TonemappingExposure Single Tonemapping exposure value. Inherited from TGorillaDefaultMaterialSource.
Shadows Boolean Enable shadow reception. Inherited from TGorillaDefaultMaterialSource.
ShadowMethod TGorillaShadowMethod Shadow mapping method. Inherited from TGorillaDefaultMaterialSource.
DepthPass TGorillaRenderPassController Depth render pass (if not using refraction depth). Inherited from TGorillaDefaultMaterialSource.

Public Methods

constructor Create(AOwner: TComponent); override;

Creates a new water material source instance.

Example:

var WaterMaterial := TGorillaWaterMaterialSource.Create(Self);

destructor Destroy(); override;

Destroys the water material source and releases resources.


procedure LoadFromDefinition(const ADef: TCustomDef); override;

Loads material configuration from definition file.

Parameters:

  • ADef - Definition data structure

procedure StoreToDefinition(const ADef: TCustomDef); override;

Stores material configuration to definition file.

Parameters:

  • ADef - Definition data structure

Ripple Management Methods

procedure AddRipple(APos: TVector3D); overload;

Adds a ripple at the specified 3D position. If the ripple list exceeds maximum capacity (32 ripples), the oldest ripple is removed.

Parameters:

  • APos - World-space position for the ripple center (TVector3D)

Example:

WaterMaterial.AddRipple(Vector3D(10.0, 0.0, 5.0));

procedure AddRipple(APos: TPoint3D); overload;

Adds a ripple at the specified 3D position. Overload accepting TPoint3D.

Parameters:

  • APos - World-space position for the ripple center (TPoint3D)

Example:

WaterMaterial.AddRipple(Point3D(10.0, 0.0, 5.0));

procedure AddRipples(const AArr: TArray<TVector3D>);

Adds multiple ripples from an array of positions. If the total exceeds maximum capacity, oldest ripples are removed.

Parameters:

  • AArr - Array of world-space ripple positions

Example:

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);

procedure SetRipples(const AArr: TArray<TVector3D>);

Clears all existing ripples and sets new ripples from the provided array.

Parameters:

  • AArr - Array of world-space ripple positions (replaces all existing ripples)

Example:

var NewRipples: TArray<TVector3D>;
SetLength(NewRipples, 2);
NewRipples[0] := Vector3D(0, 0, 0);
NewRipples[1] := Vector3D(10, 0, 0);
WaterMaterial.SetRipples(NewRipples);

procedure ClearRipples();

Removes all active ripples from the water surface.

Example:

WaterMaterial.ClearRipples();

TGorillaWaterMaterial

Internal material class that performs shader compilation and rendering. Not directly instantiated by user code.

Inheritance: TGorillaDefaultMaterial → TGorillaWaterMaterial

Public Properties

Property Type Description
WaveSpeed Single Wave animation speed (read/write).
WaveSize Single Wave distortion amplitude (read/write).
DiffusePower Single Diffuse/refraction mix ratio (read/write).
FoamDirection TPointF Foam movement direction (read/write).
FoamIntensity Single Foam brightness (read/write).
OutputLayer TWaterOutputLayer Debug output mode (read/write).
ReflCorrection TVector3D Reflection color correction (read/write).
RefrCorrection TVector3D Refraction color correction (read/write).
DepthIntensity Single Depth influence (read/write).
ShoreWidth Single Shore effect range (read/write).
ShoreIntensity Single Shore foam brightness (read/write).
DisplIntensity Single Displacement strength (read/write).
DUDVTexture TTexture DUDV texture reference (read/write).
FoamTexture TTexture Foam texture reference (read/write).
ShoreTexture TTexture Shore texture reference (read/write).
RipplesActive Boolean Ripple computation enabled (read/write).
RippleAmplification Single Ripple height (read/write).
RippleProximity Single Ripple width (read/write).
RippleDecay Single Ripple fade speed (read/write).

Public Methods

constructor Create(const ASource: TGorillaDefaultMaterialSource); override;

Creates internal water material instance. Called automatically by TGorillaWaterMaterialSource.


destructor Destroy(); override;

Destroys material and releases GPU resources.


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

Ripple management methods (identical to TGorillaWaterMaterialSource methods).


Data Structures

TWaterParams (Uniform Buffer - OpenGL ES 3.0+)

Packed uniform buffer structure for water shader parameters (std140 layout).

Platform: {$IFDEF GL_ES_VERSION_3_0} and higher

TWaterParams = packed record
  Time           : Single;           // Current animation time
  WaveSize       : Single;           // Wave distortion strength
  WaveSpeed      : Single;           // Wave animation speed
  DiffusePower   : Single;           // Diffuse/refraction mix

  ReflCorrection : TVector3D;        // Reflection color correction (RGB)
  RefrCorrection : TVector3D;        // Refraction color correction (RGB)

  FoamDirection  : TPointF;          // Foam movement direction
  FoamIntensity  : Single;           // Foam brightness
  OutputLayer    : Single;           // Debug output layer index

  DepthIntensity : Single;           // Depth influence factor
  ShoreWidth     : Single;           // Shore effect range
  ShoreIntensity : Single;           // Shore foam brightness
  DisplIntensity : Single;           // Displacement strength

  RippleCount         : Single;      // Number of active ripples
  RippleAmplification : Single;      // Ripple height
  RippleProximity     : Single;      // Ripple width
  RippleDecay         : Single;      // Ripple fade speed
  Ripples             : Array[0..31] of TVector3D;  // Ripple positions (X, Y, Z, W=time)
end;

Memory Layout: Aligned to std140 specification for GPU uniform buffers.


Enumerations

TWaterOutputLayer

Debug visualization modes for water shader output.

TWaterOutputLayer = (
  wolAll,           // Normal rendering (all layers combined)
  wolDUDV,          // DUDV displacement map only
  wolNormal,        // Normal map only
  wolSpecular,      // Specular highlights only
  wolFoam,          // Foam layer only
  wolDepth,         // Depth map visualization
  wolRefraction,    // Refraction pass only
  wolReflection,    // Reflection pass only
  wolReflPlusRefr,  // Reflection + refraction blend
  wolTexCoords      // Texture coordinates visualization
);

Usage:

WaterMaterial.OutputLayer := wolDepth;  // Visualize depth map

Constants

Texture Unit Assignments

WATER_TEX_DUDV  = 0;  // DUDV displacement texture
WATER_TEX_FOAM  = 1;  // Foam texture
WATER_TEX_SHORE = 2;  // Shore foam texture
WATER_TEX_SPEC  = 3;  // Specular map
WATER_TEX_NRML  = 4;  // Normal map
WATER_TEX_DSPL  = 5;  // Displacement map
WATER_TEX_DPTH  = 6;  // Depth map (from pass)
WATER_TEX_REFR  = 7;  // Refraction texture
WATER_TEX_REFL  = 8;  // Reflection texture
WATER_TEX_ENVM  = 7;  // Environment map (cubemap)

Ripple Limits

MAX_RIPPLES = 32;  // Maximum simultaneous ripples (platform-dependent)

Platform Notes:

  • Desktop (OpenGL 4.3+): 32 ripples
  • Mobile (GLES 3.0+): 32 ripples

Extension Identifier

GORILLA_WATER_EXTENSION_DEF = 'Water';  // Material extension name

Shader Implementation Details

GLSL Shader Structure

The water shader implements a multi-stage rendering pipeline:

  1. Vertex Shader:

    • Displacement mapping (if enabled)
    • Tangent-space calculations
    • Reflection/refraction coordinate projection
  2. Fragment Shader:

    • DUDV-based distortion computation
    • Depth map sampling
    • Reflection/refraction blending
    • Normal mapping
    • Specular highlights
    • Foam overlay
    • Shore foam generation
    • Ripple computation

Key GLSL Functions

// Get distorted texture coordinates
vec4 getDistortedTexCoord(
  in sampler2D p_Tex,
  in vec2 p_OrigTexCoord,
  in vec2 p_OrigTiling,
  in float p_MoveFac,
  in float p_Strength
);

// Compute depth from depth/refraction texture
float getDepth(in sampler2D tex, in WaterSurfaceInput p_Input);

// Get reflection color
vec4 getReflection(in sampler2D tex, in WaterSurfaceInput p_Input);
vec4 getReflection(in samplerCube tex, in WaterSurfaceInput p_Input);  // Cubemap variant

// Get refraction color
vec4 getRefraction(in sampler2D tex, in WaterSurfaceInput p_Input);
vec4 getRefraction(in samplerCube tex, in WaterSurfaceInput p_Input);  // Cubemap variant

// Main water surface computation
void WaterSurface(
  in sampler2D depthTex,
  in sampler2D reflTex,
  in sampler2D refrTex,
  in sampler2D dudvTex,
  in sampler2D foamTex,
  in sampler2D shoreTex,
  in sampler2D normalMap,
  in sampler2D specMap,
  inout WaterSurfaceInput p_Input,
  out WaterSurfaceOutput p_Output
);

Usage Examples

Basic Water Material

var
  WaterMaterial: TGorillaWaterMaterialSource;
begin
  WaterMaterial := TGorillaWaterMaterialSource.Create(Self);

  // Configure appearance
  WaterMaterial.Diffuse := TAlphaColorF.Create(0.1, 0.3, 0.5, 0.8);
  WaterMaterial.Specular := TAlphaColorF.Create(1.0, 1.0, 1.0, 1.0);
  WaterMaterial.Shininess := 128.0;

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

  // Configure waves
  WaterMaterial.WaveSpeed := 1.0;
  WaterMaterial.WaveSize := 1.2;
end;

Water with Reflection and Refraction

var
  WaterMaterial: TGorillaWaterMaterialSource;
  ReflectionPass: TGorillaRenderPassReflection;
  RefractionPass: TGorillaRenderPassRefraction;
begin
  // Create render passes (see TGorillaRenderPassReflection/Refraction docs)
  ReflectionPass := CreateReflectionPass();
  RefractionPass := CreateRefractionPass();

  WaterMaterial := TGorillaWaterMaterialSource.Create(Self);

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

  // Enable refraction
  WaterMaterial.Refractions := True;
  WaterMaterial.RefractionPass := RefractionPass;
  WaterMaterial.RefractionPower := 0.8;
  WaterMaterial.RefrCorrection := Vector3D(1.0, 1.0, 1.05);  // Slight blue tint

  // Depth configuration
  WaterMaterial.DepthIntensity := 1.0;
end;

Water with Foam and Shore Effects

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

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

Interactive Ripples

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

// Add ripple on mouse click
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 := Viewport.ScreenToWorld(PointF(X, Y));
    WaterMaterial.AddRipple(Point3D(LPt3D.X, LPt3D.Z, -LPt3D.Y));
  end;
end;

Displacement Mapping

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

// Adjust render pass planes for displacement offset
ReflectionPass.MirrorPosition.Point := TPoint3D(WaterPlane.AbsolutePosition) + Point3D(0, -WaterMaterial.DisplIntensity, 0);

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

Debug Output Layers

// Visualize different shader layers
WaterMaterial.OutputLayer := wolDepth;        // Show depth map
WaterMaterial.OutputLayer := wolReflection;   // Show reflections only
WaterMaterial.OutputLayer := wolDUDV;         // Show DUDV displacement
WaterMaterial.OutputLayer := wolAll;          // Return to normal rendering

Important Notes

  1. Render Pass Requirements: Water material REQUIRES both reflection and refraction passes. Water will appear black or incorrect without properly configured passes.

  2. Plane Exclusion: The water mesh MUST be excluded from reflection and refraction passes using IgnoreControl() to prevent self-rendering artifacts.

  3. Displacement Offset: When using displacement mapping, adjust reflection/refraction plane positions to compensate for vertex offset.

  4. Ripple Limits: Maximum 32 simultaneous ripples on most platforms. Older platforms may have lower limits or no ripple support.

  5. Uniform Buffers: On OpenGL ES 3.0+, water parameters use uniform buffer objects for efficiency.

  6. Texture Requirements: Minimum required textures are DUDV and Normal maps. Other textures (specular, foam, shore, displacement) are optional.

  7. Performance: Water rendering is shader-intensive. Use lower resolution render passes on mobile platforms.

  8. Platform Differences: Some features (uniform buffers, ripple count) vary by platform and OpenGL version.

See Also