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:
-
Vertex Shader:
- Displacement mapping (if enabled)
- Tangent-space calculations
- Reflection/refraction coordinate projection
-
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
-
Render Pass Requirements: Water material REQUIRES both reflection and refraction passes. Water will appear black or incorrect without properly configured passes.
-
Plane Exclusion: The water mesh MUST be excluded from reflection and refraction passes using
IgnoreControl()to prevent self-rendering artifacts. -
Displacement Offset: When using displacement mapping, adjust reflection/refraction plane positions to compensate for vertex offset.
-
Ripple Limits: Maximum 32 simultaneous ripples on most platforms. Older platforms may have lower limits or no ripple support.
-
Uniform Buffers: On OpenGL ES 3.0+, water parameters use uniform buffer objects for efficiency.
-
Texture Requirements: Minimum required textures are DUDV and Normal maps. Other textures (specular, foam, shore, displacement) are optional.
-
Performance: Water rendering is shader-intensive. Use lower resolution render passes on mobile platforms.
-
Platform Differences: Some features (uniform buffers, ripple count) vary by platform and OpenGL version.