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
MaterialSourceproperty 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
TGorillaNodeEntitynodes - 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
- Add a
TGorillaCustomMaterialSourcecomponent to your form - Configure properties in the Object Inspector
- Assign textures via Texture properties
- Link to meshes via
MaterialSourceproperty
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 beRepeatedorMirroredRepeat. IfWrapS/WrapT(orWrapRfor 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 setRepeatedexplicitly whenTiling > 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.Enabledand supports directional, spot and point lights — see Cascaded Shadow Maps. The legacy material-levelShadowMethodflags 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
- Use Default Material: Start with
TGorillaCustomMaterialSourcefor maximum flexibility - Enable Only Needed Features: Unnecessary features impact performance
- Batch Property Changes: Use
BeginChange/EndChangefor multiple updates - Use Behaviours: Leverage behaviours for reusable effects
- PBR for Realism: Use PBR shading model for realistic rendering
- Test on Target Platform: Verify performance and light limits
- Use Appropriate Shading: Lambert for matte, Phong for shiny, PBR for realistic
- Optimize Texture Sizes: Use appropriate resolutions for target platform
- 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;