Materials

Materials in Gorilla3D define how 3D objects appear when rendered, controlling colors, textures, lighting, and advanced effects like normal mapping, PBR (Physically-Based Rendering), and shadows. The framework provides a comprehensive material system centered around TGorillaDefaultMaterialSource with 18+ specialized material types.

Important: Materials must be assigned to meshes via the MaterialSource property to be rendered.

Material Architecture

Node-Based Shader System

Gorilla3D uses a node-based architecture to automatically generate GLSL shaders at runtime. This system:

  • Composes vertex and fragment shaders hierarchically using TGorillaNodeEntity nodes
  • Prevents code duplication across different material types
  • Enables modular shader functionality through defines
  • Automatically compiles and registers shaders on the GPU

Key Components

TGorillaDefaultMaterialSource (Component)
└─ TGorillaDefaultMaterial (Material)
   ├─ Vertex Shader (TGorillaGLSLVertexShader)
   │  └─ Nodes (position, displacement, transforms)
   └─ Fragment Shader (TGorillaGLSLFragmentShader)
      └─ Nodes (lighting, textures, PBR, effects)

Default Material Source

The TGorillaDefaultMaterialSource is the primary material component providing:

  • Multiple shading models (Lambert, Phong, Blinn-Phong, PBR)
  • Comprehensive texture support (diffuse, normal, specular, emissive, displacement, etc.)
  • Advanced mapping techniques (normal mapping, bump mapping, parallax occlusion mapping)
  • Physically-Based Rendering (PBR) with metallic/roughness workflow
  • Shadow mapping support
  • Reflection and refraction
  • Fog integration
  • Material behaviours (v1.1+)

Creating a Material

Of course you can you the classical derivates of TGorillaDefaultMaterialSource like TGorillaLambertMaterialSource, TGorillaPhongMaterialSource, TGorillaBlinnMaterialSource, ...

To set up a free configurable material source, we recommend to use a TGorillaCustomMaterialSource instance. Because many properties are hidden in the TGorillaDefaultMaterialSource by default.

Design-Time

  1. Add a TGorillaCustomMaterialSource component to your form
  2. Configure properties in the Object Inspector
  3. Assign textures via Texture properties
  4. Link to meshes via MaterialSource property

Runtime

var
  Material: TGorillaCustomMaterialSource;
begin
  Material := TGorillaCustomMaterialSource.Create(Self);
  Material.Diffuse := TAlphaColorF.Create(0.8, 0.8, 0.8, 1.0);
  Material.Specular := TAlphaColorF.Create(1.0, 1.0, 1.0, 1.0);
  Material.Shininess := 32.0;

  // By default Texture0 is expected - deactivate to allow color rendering only
  Material.UseTexture0 := false;

  // Assign to mesh
  Mesh.MaterialSource := Material;
end;

Shading Models

Shading models describe the way lights interacts with a material. The shading model has direct effect to the rendering performance. So simple mechanisms like lambert are much faster in rendering than physically-based rendering.

Lambert Shading

Simple diffuse lighting without specular highlights. Best for matte surfaces.

Material.ShadingModel := TGorillaShadingModel.smLambert;
Material.Diffuse := TAlphaColorF.Create(0.7, 0.5, 0.3, 1.0);

Phong Shading

Classic lighting model with specular highlights. Good for shiny surfaces.

Material.ShadingModel := TGorillaShadingModel.smPhong;
Material.Diffuse := TAlphaColorF.Create(0.7, 0.5, 0.3, 1.0);
Material.Specular := TAlphaColorF.Create(1.0, 1.0, 1.0, 1.0);
Material.Shininess := 64.0;

Blinn-Phong Shading

Improved Phong model with better performance and visual quality.

Material.ShadingModel := TGorillaShadingModel.smBlinnPhong;
Material.Shininess := 32.0;

PBR (Physically-Based Rendering)

Realistic rendering using physical properties (metalness, roughness).

Material.ShadingModel := TGorillaShadingModel.smPBR;
Material.MetallicBias := 0.8;   // 0=dielectric, 1=metal
Material.RoughnessBias := 0.3;  // 0=smooth, 1=rough
Material.AOBias := 1.0;          // Ambient occlusion

For extended PBR rendering special textures for those elements are needed. To activate the texture usage for a property use UsePBRAlbedoTexture, UsePBRAOTexture, UsePBRMetallicTexture, UsePBRRoughnessTexture or UsePBREmissiveTexture.

Texture Mapping

Diffuse Texture

Base color/albedo map:

Material.UseTexturing := True;
Material.UseTexture0 := True;
Material.Texture.LoadFromFile('diffuse.png');

Texture Tiling

Every texture in a material lives in the material's bitmap pool (the Bitmaps property, a TGorillaBitmapPool of TGorillaBitmapPoolEntry items). Beside the raw image (Bitmap), each entry carries GPU sampling settings — among them Tiling and the Wrap modes.

Tiling (TPointF, default (1.0, 1.0)) controls how often the texture repeats across the surface UVs. The scalar components TilingX / TilingY address the axes individually:

// Repeat the diffuse texture 8×8 times
Material.Bitmaps.Items[0].Tiling := PointF(8.0, 8.0);
Material.Bitmaps.Items[0].WrapS  := TGorillaTextureWrap.Repeated;
Material.Bitmaps.Items[0].WrapT  := TGorillaTextureWrap.Repeated;

Important — black seam lines when tiling: Tiling is computed in GLSL via mod(texcoord * tiling, 1.0) and therefore works regardless of the wrap mode. But for seamless tiles the wrap mode must be Repeated or MirroredRepeat. If WrapS / WrapT (or WrapR for 3D textures) is left at a clamping mode (Clamp, ClampToEdge, ClampToBorder), the filter footprint at each tile seam clamps to the texture border and produces visible dark / black lines along the tile edges. A fresh bitmap entry defaults to a clamping wrap mode, so always set Repeated explicitly when Tiling > 1.

See Default Material → The Bitmaps Property for the full property list.

Normal Mapping

Surface detail without geometry:

Material.UseNormalMapping := True;
Material.NormalMap.LoadFromFile('normal.png');

Material.NormalIntensity := 1.0;  // Adjust bump intensity
Material.InverseNormalMapping := False;  // Set True for DirectX-style normals

Parallax Occlusion Mapping (POM)

Advanced depth mapping for realistic surface detail:

Material.UseParallaxOcclusionMapping := True;
Material.ParallaxOcclusionMap.LoadFromFile('pom_map.png');

Material.ParallaxLevels := 64;  // 4-256 (higher = better quality, lower performance)
Material.NormalIntensity := 0.1;  // Adjust parallax shifting intensity

Specular Mapping

Controls specular highlights per-pixel:

Material.UseSpecular := true;
Material.UseSpecularMapping := True;
Material.SpecularMap.LoadFromFile('specular.png');

Emissive Mapping

Self-illuminating surfaces (glow effects):

Material.UseEmissiveColoring := True;
Material.UseEmissiveMapping := True;
Material.EmissiveMap := LoadBitmapFromFile('emissive.png');

// The color contains the base color for emission in RGB.
// The A (alpha) value is used for color intensity.
Material.Emissive := TAlphaColorF.Create(1.0, 0.8, 0.2, 1.0);

Opacity Mapping

Transparency control via texture:

Material.UseOpacityMapping := True;
Material.OpacityMap := LoadBitmapFromFile('opacity.png');

Displacement Mapping

Actual geometry displacement in vertex shader:

Material.UseDisplacementMapping := True;
Material.UseDisplacementTexture := True;
Material.DisplacementMap := LoadBitmapFromFile('displacement.png');

// Displacement scalar vector: Use (x, y, z) as scaling value for applying onto the normal of each vertex.
// w is the displacement direction, while -1 means shrinking, but +1 means extrusion.
Material.Displacement := Vector3D(0, 1, 0, 1);

PBR Texture Workflow

To use a physically-based material, place a TGorillaPBRMaterialSource component onto your form. Only then the full feature-set for PBR is available by default.

Full PBR material with texture maps:

Material.ShadingModel := TGorillaShadingModel.smPBR;

// Albedo (base color)
Material.UsePBRAlbedoTexture := True;
Material.Texture0.LoadFromFile('albedo.png');

// Metalness
Material.UsePBRMetallicTexture := True;
Material.MetalnessTexture.LoadFromFile('metallic.png');

// Roughness
Material.UsePBRRoughnessTexture := True;
Material.RoughnessTexture.LoadFromFile('roughness.png');

// Ambient Occlusion
Material.UsePBRAOTexture := True;
Material.AmbientOcclusionTexture.LoadFromFile('ao.png');

// Normal map
Material.UseNormalMapping := True;
Material.NormalMap.LoadFromFile('normal.png');
Material.NormalIntensity := 1.0;

// Emissive
Material.UsePBREmissiveTexture := True;
Material.EmissiveMap.LoadFromFile('emissive.png');

// Specular
Material.UsePBRSpecularTexture := True;
Material.SpecularMap.LoadFromFile('specular.png');

// Parallax Occlusion Mapping
Material.UseParallaxOcclusion := True;
Material.ParallaxOcclusionMap.LoadFromFile('pom_map.png');
Material.ParallaxLevels := 64;
Material.NormalIntensity := 0.1;

// Opacity mapping
Material.UseOpacityMapping := true;
Material.OpacityMap.LoadFromFile('opacity.png');

Advanced Features

Shadow Mapping

Recommended: For shadows, use the Cascaded Shadow Maps (CSM) system. It is enabled per-viewport via Viewport.Shadows.Enabled and supports directional, spot and point lights — see Cascaded Shadow Maps. The legacy material-level ShadowMethod flags below are kept for compatibility.

To receive CSM shadows, a material opts in with Shadows := True and ShadowMethod := TGorillaShadowMethod.CascadedShadowMapping — no shadow pass needs to be wired up manually:

// Viewport side (once): enable and tune the system
GorillaViewport1.Shadows.Enabled  := True;
GorillaViewport1.Shadows.Strength := 0.8;   // global shadow darkness [0..1]
MyDirLight.CastShadow             := True;

// Material side: receive cascaded shadows
Material.Shadows      := True;
Material.ShadowMethod := TGorillaShadowMethod.CascadedShadowMapping;

For legacy shadow map rendering an attached shadow rendering pass is needed.

Warning: The material-level ShadowMapping and VarianceShadowMapping feature is not fully implemented and might lead to unexpected behaviour.

Enable shadow reception:

Material.Shadows := True;
Material.ShadowMethod := TGorillaShadowMethod.smShadowMapping;  // or smVSM
Material.ShadowMapPass[0] := GorillaRenderPassSMStoreDepth1;

Reflections and Refractions

For correct planar reflection and refraction computation, you will need a linked TGorillaRenderPassReflection and TGorillaRenderPassRefraction render pass controller component.

// Reflections
GorillaRenderPassReflection1 := TGorillaRenderPassReflection.Create(GorillaViewport1);
GorillaRenderPassReflection1.Parent := GorillaViewport1;
GorillaRenderPassReflection1.Viewport := GorillaViewport1;
GorillaRenderPassReflection1.Camera := GorillaCamera1;
GorillaRenderPassReflection1.MirrorPosition.Point := TPoint3D.Zero;
GorillaRenderPassReflection1.Enabled := True;

Material.Reflections := True;
Material.ReflectionPower := 0.5;  // 0-1
Material.ReflectionPass := GorillaRenderPassReflection1;

// Refractions
GorillaRenderPassRefraction1 := TGorillaRenderPassRefraction.Create(GorillaViewport1);
GorillaRenderPassRefraction1.Parent := GorillaViewport1;
GorillaRenderPassRefraction1.Viewport := GorillaViewport1;
GorillaRenderPassRefraction1.Enabled := True;

Material.Refractions := True;
Material.RefractionPower := 0.8;
Material.UseRefractionDepth := True;
Material.RefractionPass := GorillaRenderPassRefraction1;

Environment Mapping

For correct environment mapping rendering, you will need a linked TGorillaRenderPassEnvironment component. Because it's not a static image used to produce a result. Instead the computation basis comes from a separated render pass.

Cube map reflections:

GorillaRenderPassEnvironment1 := TGorillaRenderPassEnvironment.Create(GorillaViewport1);
GorillaRenderPassEnvironment1.Parent := GorillaViewport1;
GorillaRenderPassEnvironment1.Viewport := GorillaViewport1;
GorillaRenderPassEnvironment1.IsDynamic := True;
GorillaRenderPassEnvironment1.Enabled := True;

Material.Environment := True;
Material.EnvironmentPass := GorillaRenderPassEnvironment1;

Depth Mapping

The depth information is used for some kind of effects in specific materials. A good example is here TGorillaWaterMaterialSource. It uses the depth value of the pre-rendered scene to perform blending on water edges and on changing the color with the depth of water.


GorillaRenderPassCustomDepth1 := TGorillaRenderPassCustomDepth.Create(GorillaViewport1);
GorillaRenderPassCustomDepth1.Parent := GorillaViewport1;
GorillaRenderPassCustomDepth1.Viewport := GorillaViewport1;

// TDepthMethod: dmDefault, dmMVPPosZ, dmModelViewPosZ
GorillaRenderPassCustomDepth1.DepthMethod := dmDefault;
GorillaRenderPassCustomDepth1.Enabled := true;

Material.UseDepthMap := True;
Material.DepthPass := GorillaRenderPassCustomDepth1;

Vertex Coloring

Each vertex is able to hold a color information. To render this color instead of a texture color, you need to activate UseVertexColor property. This property stands in conflict with UseTexturing property. If UseVertexColor is set to True, the possibly assigned texture diffuse color is getting ignored. Instead the vertex color will be used in the current fragment.

It's allowed to activate UseLighting for vertex coloring. In case you want flat colors, deactivate this property.

Material.UseVertexColor := True;

Alpha Cutoff

Discard fragments below threshold (for foliage, chains, etc.):

Material.UseAlphaCutoff := True;
Material.AlphaCutoff := 0.5;  // 0-1

Tonemapping

Tonemapping means modifying the final color of a material in a specific and predefined style. Gorilla3D offers a few classic styles for coloring, which are available by the TGorillaTonemapping type.

Value Description
tmNone No tonemapping.
tmExposure Simple exposure adjustment.
tmNarkowicz ACES Narkowicz approximation.
tmHill ACES Hill operator.
tmHillBoost ACES Hill with exposure boost.
tmReinhard Reinhard operator.
tmLumaBasedReinhard Luminance-based Reinhard.
tmWhitePreservingLumaBasedReinhard White-preserving Reinhard.
tmRomBinDaHouse RomBinDaHouse operator.
tmFilmic Filmic operator.
tmUncharted2 Uncharted 2 operator.
Material.Tonemapping := TGorillaTonemapping.tmFilmic;  // Recommended
// Options: tmNone, tmReinhard, tmUncharted2, tmFilmic, etc.
Material.TonemappingExposure := 1.0;

Color Clipping

Discard pixels matching specific color:

Material.UseColorClipping := True;
Material.ClippingColor := TAlphaColorF.Create(1, 0, 1, 1);  // Magenta

Material Behaviours

Material behaviours (v1.1+) provide modular, reusable shader functionality that can be attached to any material source.

Built-in Behaviours

Behaviour Description Use Case
TGorillaWindBehaviour Wind animation system Grass, trees, flags
TGorillaWobbleBehaviour Wobble effect Jelly, soft bodies
TGorillaRimLightBehaviour Rim/edge lighting Character outlines, highlights
TGorillaCausticsBehaviour Caustics effects Underwater scenes
TGorillaColorAdjustBehaviour Color adjustments Hue, saturation, brightness

Using Behaviours

var
  WindBehaviour: TGorillaWindBehaviour;
begin
  // Create behaviour component
  WindBehaviour := TGorillaWindBehaviour.Create(Self);
  WindBehaviour.Viewport := Viewport;
  WindBehaviour.Strength := 0.5;
  WindBehaviour.Speed := 1.0;

  // Attach to material
  Material.AttachMaterialBehaviour(WindBehaviour);
end;

Behaviour Advantages

  • Centralized Parameters: Single behaviour instance controls multiple materials
  • Code Reuse: Share shader code across different material types
  • Easy Maintenance: Update effect in one place
  • Performance: Efficient uniform buffer management

Specialized Material Types

Gorilla3D includes specialized materials for specific use cases:

TGorillaLambertMaterialSource

Simple Lambert shading without specular.

TGorillaPhongMaterialSource

Phong shading with specular highlights.

TGorillaBlinnMaterialSource

Blinn-Phong shading (optimized Phong).

TGorillaPBRMaterialSource

Dedicated PBR material.

TGorillaBumpMapMaterialSource

Bump mapping without normal maps.

TGorillaNormalMapMaterialSource

Normal mapping only.

TGorillaPOMMaterialSource

Parallax occlusion mapping.

TGorillaRimLightingMaterialSource

Rim/edge lighting effects.

TGorillaVertexColorMaterialSource

Vertex color only (no textures).

TGorillaWaterMaterialSource

Animated water surface.

TGorillaGrassMaterialSource

Grass rendering with wind.

TGorillaParticleMaterialSource

Particle system rendering.

TGorillaTerrainMaterialSource

Terrain with height-based texturing.

TGorillaSplatMapMaterialSource

Multi-texture terrain blending.

TGorillaLayeredMaterialSource

Multiple texture layers with blending.

TGorillaAtlasMaterialSource

Texture atlas support.

TGorillaGridMaterialSource

Debug grid rendering.

TGorillaSharedMaterialSource

Share material data across instances.

TGorillaRuntimeMaterialSource

Create materials at runtime.

TGorillaCustomMaterialSource

Custom shader code.

Uniform Buffer System

Materials use TGorillaShaderData structure for efficient GPU data transfer:

TGorillaShaderData = packed record
  ModelViewProjectionMatrix: TMatrix3D;
  ViewMatrix: TMatrix3D;
  ProjectionMatrix: TMatrix3D;
  TimeInfo: TVector3D;
  EyePos: TVector3D;
  ViewDir: TPoint3D;
  ShadingModel: FixedInt;
  Material: TGorillaShaderMaterial;
  Lights: Array of TGorillaShaderLight;
  LightsCount: FixedInt;
  FogMode: FixedInt;
  FogDensity, FogStart, FogEnd: Single;
  FogColor: TAlphaColorF;
  // ... many more fields
end;

Performance Optimization

Material Batching

Use BeginChange/EndChange to batch property updates:

Material.BeginChange();
try
  Material.Diffuse := NewDiffuse;
  Material.Specular := NewSpecular;
  Material.Shininess := NewShininess;
finally
  Material.EndChange();
end;

Texture Management

// Efficient texture loading
Material.Texture := LoadBitmapFromFile('texture.png');

// Share textures across materials
Material2.Texture := Material1.Texture;

Shader Caching

Shaders are automatically cached by the engine based on active features.

Light Limits

Platform-dependent light counts:

Platform OpenGL ES 3.0 Metal/OpenGL 4.3+
Windows - 32 lights
Linux - 32 lights
Android 8 lights -
macOS - 32 lights
iOS - 8 lights

Best Practices

  1. Use Default Material: Start with TGorillaCustomMaterialSource for maximum flexibility
  2. Enable Only Needed Features: Unnecessary features impact performance
  3. Batch Property Changes: Use BeginChange/EndChange for multiple updates
  4. Use Behaviours: Leverage behaviours for reusable effects
  5. PBR for Realism: Use PBR shading model for realistic rendering
  6. Test on Target Platform: Verify performance and light limits
  7. Use Appropriate Shading: Lambert for matte, Phong for shiny, PBR for realistic
  8. Optimize Texture Sizes: Use appropriate resolutions for target platform
  9. Monitor Shader Rebuilds: Changing material properties may trigger shader recompilation

Common Patterns

Metallic Surface

Material.ShadingModel := TGorillaShadingModel.smPBR;
Material.MetallicBias := 1.0;
Material.RoughnessBias := 0.1;
Material.Diffuse := TAlphaColorF.Create(0.9, 0.9, 0.9, 1.0);

Rough Stone

Material.ShadingModel := TGorillaShadingModel.smPBR;
Material.MetallicBias := 0.0;
Material.RoughnessBias := 0.9;
Material.UseNormalMapping := True;

Glowing Object

Material.UseEmissiveColoring := True;
Material.Emissive := TAlphaColorF.Create(1.0, 0.5, 0.0, 1.0);
Material.UseEmissiveMapping := True;
Material.EmissiveTexture := GlowTexture;

Transparent Glass

Material.Diffuse := TAlphaColorF.Create(0.9, 0.9, 1.0, 0.3);
Material.Refractions := True;
Material.RefractionPower := 0.9;
Material.UseSpecular := True;
Material.Shininess := 128.0;

See Also