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/indices
  • ASize - 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 values
  • ASmoothing - 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/indices
  • ASubDivAxes - Sphere axes subdivisions (longitude)
  • ASubDivHeight - Height subdivisions (latitude)
  • ATwoFace - Generate back faces
  • AHeightMap - Source heightmap bitmap
  • AHeightScale - Deformation scale from sphere surface
  • ASmoothing - 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

  1. Match heightmap to resolution - Avoid upscaling/downscaling
  2. Use smoothing judiciously - Each iteration adds processing time
  3. Disable TwoFace - Halves index count
  4. Static buffering - Upload to GPU, clear local data
  5. Decimation - Reduce vertices after generation

See Also