Gorilla.Terrain.Utils Unit Reference
Helper classes for terrain mesh generation.
Unit: Gorilla.Terrain.Utils
TGorillaTerrainHelper
Static helper class for low-level terrain generation.
Usage: Called internally by terrain components. Advanced users can use these methods directly for custom terrain generation.
Methods
BuildTerrainFromHeightMap
class procedure BuildTerrainFromHeightMap(
const AMeshData: TMeshData;
const ASize: TPoint3D;
const ASubDivWidth, ASubDivHeight: Integer;
const ATwoFace: Boolean;
const AHeightMap: TBitmap;
const AHeightScale: Single;
const ASmoothing: Integer);
Builds planar terrain mesh from heightmap.
Parameters:
AMeshData- Target mesh data for vertices/indicesASize- Terrain dimensions (Width, Height, Depth)ASubDivWidth- X-axis subdivisions (columns)ASubDivHeight- Z-axis subdivisions (rows)ATwoFace- Generate back faces (two-sided rendering)AHeightMap- Source heightmap bitmap (grayscale or color)AHeightScale- Y-axis multiplier for height valuesASmoothing- Smoothing iterations (0-20)
Remarks:
- Generates vertices positioned on a grid from -0.5 to +0.5 in X and Z
- Height is sampled from heightmap and applied to Y-axis
- Normals, tangents, and binormals are calculated automatically
- If heightmap is smaller than grid resolution, pixels are interpolated
- Smoothing applies blur filter to heightmap before vertex generation
Example:
var
LMeshData: TMeshData;
LHeightMap: TBitmap;
begin
LMeshData := TMeshData.Create;
LHeightMap := TBitmap.Create;
try
LHeightMap.LoadFromFile('heightmap.png');
TGorillaTerrainHelper.BuildTerrainFromHeightMap(
LMeshData,
Point3D(100, 20, 100), // Size
256, 256, // Resolution
False, // TwoFace
LHeightMap,
1.0, // HeightScale
5 // Smoothing
);
// Use LMeshData for custom rendering
finally
LHeightMap.Free;
LMeshData.Free;
end;
end;
BuildSphereTerrainFromHeightMap
class procedure BuildSphereTerrainFromHeightMap(
const AMeshData: TMeshData;
const ASubDivAxes, ASubDivHeight: Integer;
const ATwoFace: Boolean;
const AHeightMap: TBitmap;
const AHeightScale: Single;
const ASmoothing: Integer);
Builds spherical terrain mesh from heightmap.
Parameters:
AMeshData- Target mesh data for vertices/indicesASubDivAxes- Sphere axes subdivisions (longitude)ASubDivHeight- Height subdivisions (latitude)ATwoFace- Generate back facesAHeightMap- Source heightmap bitmapAHeightScale- Deformation scale from sphere surfaceASmoothing- Smoothing iterations (0-20)
Remarks:
- Generates a UV-sphere with radius 0.5
- Heightmap deforms vertices along their normals
- Texture coordinates are mapped to sphere surface
- Useful for planetary terrain
Example:
var
LMeshData: TMeshData;
LHeightMap: TBitmap;
begin
LMeshData := TMeshData.Create;
LHeightMap := TBitmap.Create;
try
LHeightMap.LoadFromFile('planet_heightmap.png');
TGorillaTerrainHelper.BuildSphereTerrainFromHeightMap(
LMeshData,
512, // Axes
512, // Height
False, // TwoFace
LHeightMap,
0.1, // HeightScale
3 // Smoothing
);
// Use LMeshData for custom planet rendering
finally
LHeightMap.Free;
LMeshData.Free;
end;
end;
Implementation Details
Heightmap Sampling
The helper methods sample heightmap values using normalized coordinates:
// Normalized grid position (0..1)
LNormX := VertexX / SubdivisionsWidth;
LNormZ := VertexZ / SubdivisionsHeight;
// Map to heightmap pixel
LPixelX := Round(LNormX * HeightMap.Width);
LPixelY := Round(LNormZ * HeightMap.Height);
// Get height from pixel luminance
LHeight := PixelLuminance / 255.0;
Smoothing Algorithm
When smoothing is enabled, a 3×3 blur kernel is applied:
1 2 1
2 4 2
1 2 1
Each smoothing iteration averages neighboring pixels weighted by this kernel.
Vertex Generation
Planar Terrain:
- Vertices positioned on XZ plane
- Y-coordinate determined by heightmap
- Grid centered at origin
- Normals calculated from face geometry
Spherical Terrain:
- Vertices positioned on sphere surface using spherical coordinates
- Deformed along normal direction by heightmap value
- Texture coordinates mapped to sphere UV
Triangle Winding
Both methods generate triangles with counter-clockwise winding:
v0---v1
| \ |
| \|
v2---v3
Triangle 1: v0, v2, v1
Triangle 2: v1, v2, v3
Advanced Usage
Custom Terrain Generation
You can use these helpers for custom terrain systems:
type
TMyTerrainComponent = class(TCustomMesh3D)
private
procedure GenerateCustomTerrain;
end;
procedure TMyTerrainComponent.GenerateCustomTerrain;
var
LMeshData: TMeshData;
LHeightMap: TBitmap;
begin
LMeshData := GetMeshData();
if not Assigned(LMeshData) then Exit;
LHeightMap := GenerateProceduralHeightMap(); // Your method
try
TGorillaTerrainHelper.BuildTerrainFromHeightMap(
LMeshData,
Point3D(Width, Height, Depth),
FResolutionX, FResolutionY,
False,
LHeightMap,
1.0,
0
);
// Post-processing
ApplyCustomShading(LMeshData);
OptimizeMesh(LMeshData);
finally
LHeightMap.Free;
end;
end;
Multi-Layer Terrain
Combine multiple heightmaps:
procedure GenerateMultiLayerTerrain(AMeshData: TMeshData);
var
LBase, LDetail1, LDetail2: TBitmap;
LCombined: TBitmap;
begin
// Load separate heightmaps
LBase := LoadHeightMap('base_terrain.png');
LDetail1 := LoadHeightMap('detail_rocks.png');
LDetail2 := LoadHeightMap('detail_erosion.png');
try
// Combine heightmaps
LCombined := BlendHeightMaps([LBase, LDetail1, LDetail2],
[0.7, 0.2, 0.1]); // Weights
TGorillaTerrainHelper.BuildTerrainFromHeightMap(
AMeshData, TerrainSize, ResX, ResY, False,
LCombined, 1.0, 5
);
finally
LBase.Free;
LDetail1.Free;
LDetail2.Free;
LCombined.Free;
end;
end;
Performance Considerations
Memory Usage
The helper methods allocate vertex and index buffers based on resolution:
Planar Terrain:
- Vertices:
(SubDivWidth + 1) × (SubDivHeight + 1) - Indices:
SubDivWidth × SubDivHeight × 6
Spherical Terrain:
- Vertices:
(SubDivAxes + 1) × (SubDivHeight + 1) - Indices:
SubDivAxes × SubDivHeight × 6
Optimization Tips
- Match heightmap to resolution - Avoid upscaling/downscaling
- Use smoothing judiciously - Each iteration adds processing time
- Disable TwoFace - Halves index count
- Static buffering - Upload to GPU, clear local data
- Decimation - Reduce vertices after generation
See Also
- Gorilla.Terrain - Main terrain component
- Gorilla.Terrain.Sphere - Spherical terrain