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:
- Mesh:
TGorillaPlaneor custom water mesh - Material:
TGorillaWaterMaterialSource - Reflection Pass:
TGorillaRenderPassReflection - Refraction Pass:
TGorillaRenderPassRefraction - 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: TBitmapDisplacement: TVector3D- Direction vectorDisplIntensity: 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 directionFoamIntensity: 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
-
Subdivision Density: Higher mesh subdivision improves displacement mapping but increases vertex processing cost.
-
Render Pass Resolution: Lower resolution reflection/refraction textures improve performance significantly.
-
Ripple Count: Each active ripple adds computation cost. Limit simultaneous ripples for best performance.
-
Texture Sizes: Use power-of-two textures (256x256, 512x512) for optimal GPU performance.
-
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
ReflectionsandRefractionsare enabled - Check
ReflectionPassandRefractionPassare 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.