DefaultMaterial

The default material is the approach to centralize basic shader operations, like:

• vertex transformation
• displacement mapping
• handling of multiple light sources
• handling of different light types: directional, spot or point light
• texture tiling
• normal mapping
• parallax occlusion mapping
• various shading models: lambert, phong, blinn-phong, PBR
• plane clipping
• color clipping
• color computation by ambient, diffuse, specular and emissive color
• point sprite rendering (particle effects)
• fog
• shadowing: shadow mapping or variant shadow mapping
• weighted blended order independent transparency
• reflection, refraction and environment mapping

The simple reason is that those functionality is used in nearly all materials and should not be reinvented each time. Those operations also getting very complex in combination and its hard to keep them still efficient.

The default material uses a node based memory structure to build shader source code. This means that each shader (vertex- and fragmentshader) holds a nodes hierarchy from which the shader source code is generated from.

Source code getting build by a TGorillaNodeBuilder instance, which each shader provides. The attached nodes are TGorillaNodeEntity instances or inherited from that class. When the shader is getting compiled, the ToString() method is getting called for each node in hierarchy. Depending on the activated defines, the node itself decides how its output code looks like.

This is a very flexible way and allows to modify or replace specific nodes, to produce your own shader code.

On rendering, the source code will automatically be compiled and registered in GPU.

The default vertex shader is setting up the following node hierarchy.

Root
  * SourceCode [TGorillaCompositeNode]
    - <0> [TGorillaGLSLPragma]
    - Globals [TGorillaGlobalsNode]
      - Constants [TGorillaCompositeNode]
      - Types [TGorillaCompositeNode]
        - <0> [TGorillaGLSLLightType] // DEACTIVATED
        - <1> [TGorillaGLSLTextureType] // DEACTIVATED
        - <2> [TGorillaGLSLMaterialType] // DEACTIVATED
        - <3> [TGorillaGLSLPassDataType]
        - <4> [TGorillaGLSLVertexShaderLocalsStructNode]
      - Attributes [TGorillaCompositeNode]
        - <0> [TGorillaGLSLAttributesNode]
      - Uniforms [TGorillaUniformsNode]
        - <0> [TGorillaGLSLUBOShaderData]
      - Varying [TGorillaCompositeNode]
        - <0> [TGorillaGLSLInOutNode]
      - Functions [TGorillaCompositeNode]
        - <0> [TGorillaGLSLTransformFuncsNode]
        - <1> [TGorillaGLSLGetTextureFuncsNode]
        - <2> [TGorillaVertexShaderFuncNode]
      - Variables [TGorillaCompositeNode]
  -  EntryPoint [TGorillaGLSLMainNode]
    - <0> [TGorillaGLSLVertexShaderLocalsNode]
    - <1> [TGorillaGLSLMatricesOutNode]
    - <2> [TGorillaGLSLGetVertexPositionNode]
    - <3> [TGorillaGLSLDisplacementMappingGetNode]
    - <4> [TGorillaGLSLDisplacementMappingApplyNode]
    - <5> [TGorillaGLSLClippingPlaneGetNode]
    - <6> [TGorillaGLSLVertexShaderOutputNode]
    - <7> [TGorillaGLSLAdjustPointSizeNode]
    - SurfaceShader [TGorillaSurfaceShaderNode]
      - <0> [TGorillaGLSLVertexShaderExec]
      - <1> [TGorillaGLSLVertexPositionOutputNode]

The default fragment shader is setting up the following node hierarchy.

Root
  * SourcCode [TGorillaCompositeNode]
    - <0> [TGorillaGLSLPragma]
    - Globals [TGorillaGlobalsNode]
      - Constants [TGorillaCompositeNode]
      - Types [TGorillaCompositeNode]
        - <0> [TGorillaGLSLLightType]
        - <1> [TGorillaGLSLTextureType]
        - <2> [TGorillaGLSLMaterialType]
        - <3> [TGorillaGLSLPassDataType]
        - <4> [TGorillaGLSLFragmentShaderLocalsStructNode]
      - Attributes [TGorillaCompositeNode]
      - Uniforms [TGorillaUniformsNode]
        - <0> [TGorillaGLSLUBOShaderData]
      - Varying [TGorillaCompositeNode]
        - <0> [TGorillaGLSLInOutNode]
      - Functions [TGorillaCompositeNode]
        - <0> [TGorillaGLSLPackingFuncsNode]
        - <1> [TGorillaGLSLGetDirLightDirectionFuncNode]
        - <2> [TGorillaGLSLGetPointLightDirectionFuncNode]
        - <3> [TGorillaGLSLGetSpotLightDirectionFuncNode]
        - <4> [TGorillaGLSLGetLightDirectionFuncNode]
        - <5> [TGorillaGLSLGetSpotFalloffFuncNode]
        - <6> [TGorillaGLSLGetLightAttenuationFuncNode]
        - <7> [TGorillaGLSLGetShadingFuncsNode]
        - <8> [TGorillaGLSLGetTextureFuncsNode]
        - <9> [TGorillaGLSLGetTextureAtlasFuncNode]
        - <10> [TGorillaGLSLBasicShadowFuncsNode]
        - <11> [TGorillaGLSLFaketracingShadowFuncsNode] // DEPRECATED
        - <12> [TGorillaGLSLBumpFuncsNode]
        - <13> [TGorillaGLSLPOMFuncsNode]
        - <14> [TGorillaGLSLPBRFuncsNode]
        - <15> [TGorillaGLSLFogFuncNode]
        - <16> [TGorillaSurfaceShaderFuncNode]
      - Variables [TGorillaCompositeNode]
      - <0> [TGorillaGLSLLayoutLocation] (o_Albedo)
      - <1> [TGorillaGLSLLayoutLocation] (o_Alpha)
      - <2> [TGorillaGLSLLayoutLocation] (o_Position)
      - <3> [TGorillaGLSLLayoutLocation] (o_Normals)
      - <4> [TGorillaGLSLLayoutLocation] (o_Components) // DEFERRED_RENDERING ONLY
      - <5> [TGorillaGLSLLayoutLocation] (o_Ambient) // DEFERRED_RENDERING ONLY
      - <6> [TGorillaGLSLLayoutLocation] (o_Emissive) // DEFERRED_RENDERING ONLY
      - <7> [TGorillaGLSLLayoutLocation] (o_Specular) // DEFERRED_RENDERING ONLY
    - EntryPoint [TGorillaGLSLMainNode]
      - <0> [TGorillaGLSLClippingPlaneNode]
      - <1> [TGorillaGLSLMatricesOutNode]
      - <2> [TGorillaGLSLLightingLocalsNode]
      - <3> [TGorillaGLSLSpecularColorNode]
      - <4> [TGorillaGLSLGetTransfVertPosNode]
      - <5> [TGorillaGLSLGetNormalNode]
      - <6> [TGorillaGLSLGetFragViewDirNode]
      - <7> [TGorillaGLSLTextureCoordsNode]
      - <8> [TGorillaGLSLPOMApplyNode]
      - <9> [TGorillaGLSLGetBumpNormalNode]
      - <10> [TGorillaGLSLPBRPrepareNode]
      - <11> [TGorillaGLSLLightsLoopNode]
        - <0> [TGorillaGLSLGetLightShadingNode]
        - <1> [TGorillaGLSLLightingSumNode]
        - <2> [TGorillaGLSLAddShadowNode]
        - <2> [TGorillaGLSLAddFaketracingShadowNode] // DEPRECATED
      - <12> [TGorillaGLSLPBRAmbientNode]
      - SurfaceShader [TGorillaSurfaceShaderNode]
        - <0> [TGorillaGLSLGetBaseColorNode]
        - <1> [TGorillaGLSLSpecularMapNode]
        - <2> [TGorillaGLSLAddEnvironmentNode]
        - <3> [TGorillaGLSLAddSparseVoxelsNode]
        - <4> [TGorillaGLSLAddReflectionNode]
        - <5> [TGorillaGLSLAddRefractionNode]
        - <6> [TGorillaGLSLSurfaceShaderExec]
        - <7> [TGorillaGLSLMergedColorOutputNode]
        - <8> [TGorillaGLSLBrightnessColorNode]
        - <9> [TGorillaGLSLFragColorOutputNode]
        - <10> [TGorillaGLSLColorClipNode]
        - <11> [TGorillaGLSLFogApplyNode]
        - <12> [TGorillaGLSLWeightedBlendedOITNode]

In the following we list the most common GLSL shader nodes. This should help to understand where you can manipulate or influence shader source code compilation.

At the top-level of a shader code tree either TGorillaGLSLVertexShader or TGorillaGLSLFragmentShader is attached to the node builder instance.

Attached to one of those nodes are the following container nodes:

A TGorillaGlobalsNode node automatically provides sub-containers for structuring, f.e. variables, types, functions, …

The following list is showing which node type should be inserted into which sub-container.

Not all nodes are enabled by default, so you have to unlock them by using the define management of the node builder. The following defines are provided in the default material:

To enable a shader section call: AddDefine(GORILLA_GLSL_DEFINE_*)

To disable a shader section call: RemoveDefine(GORILLA_GLSL_DEFINE_*)

In most cases definitions need to be applied to vertex- and fragmentshader, because in both shaders functionality is available.

The DefaultMaterial defines the following sections by default:

As already mentioned in the sections above, the default shader declares attributes, types, constants and variables automatically.

Those entities can be used inside the shader and can of course be modified.

In the following we list the available presets.

Each vertex provides further information besides the position of it.

But depending on the mesh data given, not all of those properties may be available.

Nevertheless the shader defines a fixed set of attributes, even if they are not filled by the mesh data.

In the current implementation of the default material a uniform buffer is used to submit settings as block to the shaders. While in previous implementations each variable was submitted separately, it became very inefficient on the large number of settings.

The default material allows to register multiple uniform buffers, but by default only the TGorillaShaderData structure is registered.

Notice: Structures inside of Delphi need a fixed alignment to OpenGL's std140 layout. You might have recognized a few “Reserved” fields. Those are marking a memory alignment inside of the structure.

Read more about OpenGL memory alignment here: https://www.khronos.org/opengl/wiki/Interface_Block_(GLSL)

The TGorillaDefaultMaterial therefore registers a packed record as exchanging buffer.

Having a closer look at the structure below, it's showing further sub structures for lights, material, textures and render pass data. Those sub structures are automatically submitted to shaders too.

  TGorillaShaderData = packed record
    /// <summary>
    /// Defines the multiplied model and view matrix.
    /// </summary>
    ModelMatrix : TMatrix3D;
    /// <summary>
    /// Defines the multiplied model, view and projection matrix.
    /// </summary>
    ModelViewProjectionMatrix : TMatrix3D;
    /// <summary>
    /// Defines the inverted and transposed multiplied model and view matrix.
    /// </summary>
    ModelNormalMatrix : TMatrix3D;
    /// <summary>
    /// Defines the view / camera matrix.
    /// </summary>
    ViewMatrix : TMatrix3D;
    /// <summary>
    /// Defines the projection matrix.
    /// </summary>
    ProjectionMatrix : TMatrix3D;
    /// <summary>
    /// Provides information about start, current, previous and delta time
    /// X - Starting time
    /// Y - Current time
    /// Z - Previous time
    /// W - Delta time
    /// </summary>
    TimeInfo : TVector3D;
    /// <summary>
    /// The absolute camera position.
    /// </summary>
    EyePos : TVector3D;
    /// <summary>
    /// The camera view direction.
    /// </summary>
    ViewDir : TPoint3D;
    /// <summary>
    /// Defines the used shading model: lambert (default), phong, blinnphong, pbr, ...
    /// </summary>
    ShadingModel : FixedInt; {TGorillaShadingModel}
    /// <summary>
    /// Defines material properties, like diffuse, specular, ambient, emissive
    /// color or information about uniform textures.
    /// </summary>
    Material : Array[0..0] of TGorillaShaderMaterial;
    /// <summary>
    /// Defines activated light sources with their properties.
    /// </summary>
    Lights : Array[0..GORILLA_MATERIAL_DEFAULT_LIGHTS-1] of TGorillaShaderLight;
    /// <summary>
    /// Defines the number of lights used in the fix-sized lights array above,
    /// beginning at 0.
    /// </summary>
    LightsCount : FixedInt;
    /// <summary>
    /// Shader specific options.
    /// </summary>
    Options : FixedInt;
 
    /// <summary>
    /// Defines how much shading is applied to diffuse and specular color.
    /// </summary>
    ShadingIntensity : Single;
    /// <summary>
    /// Defines the brightness factor applied to the diffuse color.
    /// </summary>
    Brightness : Single;
 
    /// <summary>
    /// FogMode contains information about the algorithm to be used and if
    /// fog is enabled or not.
    /// </summary>
    FogMode : FixedInt; // $01 enabled, $02 - linear, $04 - exp, $08 - exp2
    /// <summary>
    /// Defines the density of fog, used for exp and exp2 algorithm
    /// </summary>
    FogDensity : Single; // default = 0.001
    /// <summary>
    /// Defines the eye-vertex distance where fog begins.
    /// </summary>
    FogStart : Single; // default = 100.0
    /// <summary>
    /// Defines the eye-vertex distance where fog ends.
    /// </summary>
    FogEnd : Single; // default = 500.0
    /// <summary>
    /// Define the fog color used for computation.
    /// </summary>
    FogColor : TAlphaColorF; // default = vec4(0, 0, 0, 1);
 
    /// <summary>
    /// Provides the camera frustum bounding box top-left-near corner.
    /// </summary>
    FrustumMin : TVector3D;
    /// <summary>
    /// Provides the camera frustum bounding box bottom-right-far corner.
    /// </summary>
    FrustumMax : TVector3D;
    /// <summary>
    /// Provides the top-left-near corner of the scenery bounds.
    /// </summary>
    SceneMin : TVector3D;
    /// <summary>
    /// Provides the bottom-right-far corner of the scenery bounds.
    /// </summary>
    SceneMax : TVector3D;
    /// <summary>
    /// Provides the top-left-near corner of the scenery bounds.
    /// </summary>
    BoundaryMin : TVector3D;
    /// <summary>
    /// Provides the bottom-right-far corner of the scenery bounds.
    /// </summary>
    BoundaryMax : TVector3D;
 
    /// <summary>
    /// Current viewport rendering size and near / far limitation.
    /// </summary>
    /// <remarks>
    /// <para>
    /// X - viewport width
    /// </para>
    /// <para>
    /// Y - viewport height
    /// </para>
    /// <para>
    /// Z - camera frustum near
    /// </para>
    /// <para>
    /// W - camera frustum far
    /// </para>
    /// </remarks>
    ViewSize : TVector3D;
    /// <summary>
    /// You can define a single clipping plane for discarding fragments below.
    /// </summary>
    ClippingPlane : TVector3D;
 
    /// <summary>
    /// Defines some pass data information, f.e. for raytracing, reflection and refraction.
    /// </summary>
    PassData : Array[0..0] of TGorillaShaderPassData;
 
    class function Create() : TGorillaShaderData; static;
  end;

NOTICE: Properties in uniform structures need to be accessed in OpenGL shaders by prefixing those witth an underscore (“_”), even for sub-properties of sub-structures.

You can access a top-level property inside of TShaderData in OpenGL shader, like:

vars.v_Position *= _ModelMatrix;

The material property inside of the TGorillaShaderData struct defines a sub structure.

Notice: Even the material is defined as array, there is only a single material structure available.

Material : Array[0..0] of TGorillaShaderMaterial;

And the Delphi implementation of this structure is represented by the following packed record.

  TGorillaShaderMaterial = packed record
    /// <summary>
    /// Emissive color value.
    /// </summary>
    Emissive : TAlphaColorF;
    /// <summary>
    /// Ambient color value.
    /// </summary>
    Ambient : TAlphaColorF;
    /// <summary>
    /// Diffuse color value.
    /// </summary>
    Diffuse : TAlphaColorF;
    /// <summary>
    /// Specular color value.
    /// </summary>
    Specular : TAlphaColorF;
    /// <summary>
    /// Clipping color value. R/G/B is the color value, A is the tolerance.
    /// </summary>
    Clipping : TAlphaColorF;
 
    /// <summary>
    /// Displacement factor to scale the influence of a displacement map.
    /// Default value is set to vec4(0.1, 0.1, 0.1, 1.0)
    /// </summary>
    /// <remarks>
    /// <para>
    /// (x, y, z) are the extension factors applied to the vertex normal.
    /// </para>
    /// <para>
    /// w - is the extension direction, while -1 means shrinking
    /// but +1 means model extrusion.
    /// </para>
    /// </remarks>
    Displacement : TVector3D;
 
    /// <summary>
    /// X - Current object opacity value.
    /// Y - reserved for future values
    /// Z - reserved for future values
    /// W - reserved for future values
    /// </summary>
    Features : TVector3D;
 
    /// <summary>
    /// Specular shining factor. If the value is <= 1.0, shading is deativated.
    /// </summary>
    Shininess : Single;
    /// <summary>
    /// Number of all textures
    /// </summary>
    Textures : FixedInt;
    /// <summary>
    /// The index of the first pool texture to find in texture settings:
    /// _Material[0]._Texture[_Material[0]._PoolTexturesOffset]
    /// </summary>
    PoolTexturesOffset : FixedInt;
    /// <summary>
    /// Number of total pool textures.
    /// </summary>
    PoolTextures : FixedInt;
 
    /// <summary>
    /// Fixed array of texture settings.
    /// </summary>
    Texture : TGorillaShaderTextures;
 
    class function Create() : TGorillaShaderMaterial; static;
  end;

You can access material settings in OpenGL shader, f.e. by:

LOCALS.Ambient = _Material[0]._Ambient;

Each material structure TGorillaShaderMaterial supports a set of max. 16 texture structures.

// type TGorillaShaderTextures = Array[0..GORILLA_SHADER_TEXTURES_MAX - 1] of TGorillaShaderTexture;
Texture : TGorillaShaderTextures;

This allows to texture specific settings like transition values (for terrain material) or tile settings.

  TGorillaShaderTexture = packed record
    /// <summary>
    /// for terrain textures we need information about height and transition
    /// between textures - those we put inside of a vec4
    /// MinHeight, MaxHeight, LowTransition, HighTransition : Single
    /// </summary>
    Feature : TVector3D;
    /// <summary>
    /// Texture repeating value
    /// </summary>
    Tiling : TPointF;
  {$IFDEF GL_ES_VERSION_3_0}
    /// <summary>
    /// Due to memory alignment in gpu - we have to adjust memory here by
    /// some dummy bytes.
    /// </summary>
    Reserved1   : Array[0..7] of Byte;
  {$ENDIF}
  end;

You can access those settings in OpenGL shader, like:

LOCALS.Tiling.xy = _Material[0]._Texture[0]._Tiling.xy;

The default material supports multiple light sources, which are submitted inside the TGorillaShaderData uniform structure as array of TGorillaShaderLight structure.

Lights : Array[0..GORILLA_MATERIAL_DEFAULT_LIGHTS-1] of TGorillaShaderLight;

The size of that array is platform dependent.

While on Windows platforms it is limited to 32, on Android it is limited to max. 8 lights.

  TGorillaShaderLight = packed record
    LightType   : FixedInt; {TLightType}
  {$IFDEF GL_ES_VERSION_3_0}
    // due to memory alignment in gpu - we have to adjust
    Reserved1   : Array[0..11] of Byte;
  {$ENDIF}
    Position    : TVector3D;
    /// <summary>
    /// A "halfway vector" (if you mean that by "half vector") is the unit
    /// vector at the half angle between two other vectors. Normally the
    /// halfway vector [...] is computed between the vector to the viewer v
    /// and the light source.
    /// </summary>
    /// <remarks>
    /// H(a,b) = normalize(normalize(a) + normalize(b))
    /// </remarks>
//    HalfVector  : TVector3D;
    Direction   : TVector3D;
    Ambient     : TAlphaColorF;
    Diffuse     : TAlphaColorF;
    Specular    : TAlphaColorF;
 
    SpotCutoff    : Single;
    SpotCosCutoff : Single;
    SpotExponent  : Single;
 
    ConstantAttenuation  : Single;
    LinearAttenuation    : Single;
    QuadraticAttenuation : Single;
  {$IFDEF GL_ES_VERSION_3_0}
    // due to memory alignment in gpu - we have to adjust
    Reserved4   : Array[0..7] of Byte;
  {$ENDIF}
 
    constructor Create(ALight : TLightDescription);
  end;

You can access light settings in OpenGL shader, like:

LOCALS.BaseColor = _Light[0]._Diffuse;

In case you have run a render pass like reflections in a previous stage, some additional settings might be needed, like ReflectTextureMatrix or ReflectionPower.

So the PassData structure was introduced to group those settings in one place. Even if it is defined as an array, there is only a single pass data structure available.

PassData : Array[0..0] of TGorillaShaderPassData;

For more compressed data and less memory size, we merged various settings into this single structure. It might seem to be a little bit messed up, but it reduces memory usage in general.

Notice: We might refactor this structure in future, due to this confusing setup.

  TGorillaShaderPassData = packed record
    ShadowMapMatrix : Array[0..7] of TMatrix3D;
 
    ReflectTextureMatrix : TMatrix3D;
    RefractTextureMatrix : TMatrix3D;
 
    ReflectionPower : Single;
    RefractionPower : Single;
 
    TranslucentDistance : Single;
    /// <summary>
    /// A factor that is applied on the normal vector in
    /// bump mapping / normal mapping / parallax occlusion mapping.
    /// </summary>
    NormalIntensity : Single;
    /// <summary>
    /// Define the number raytracing levels during parallax occlusion mapping.
    /// Allowed values are between 4 and 256.
    /// More levels meaning less performance due to more intense gpu usage.
    /// </summary>
    ParallaxLevels : FixedInt;
 
    /// <summary>
    /// Metallic value for controlling metalness of physically based rendering output.
    /// </summary>
    PBRMetallic : Single;
    /// <summary>
    /// Roughness value for controlling noise computation of physically based rendering output.
    /// </summary>
    PBRRoughness : Single;
    /// <summary>
    /// Ambient occlusion value for controlling ambient intensity of physically based rendering output.
    /// </summary>
    PBRAO : Single;
  end;

The PassData can be access in OpenGL shader like:

LOCALS.BaseColor.xyz *= _PassData[0]._ReflectionPower;

We will not go into detail about shader stages. For further reading, please have a look at: https://www.khronos.org/opengl/wiki/Rendering_Pipeline_Overview.

But simply said, the vertex shader is computed at first and already modifies vertex position or precomputes some values, we might use in our final fragment shader.

To supply those data, we need some kind of an exchange structure. This is called varying parameter, which is represented in GLSL by the _ _ INOUT _ _ struct, accessable by the “vars.” prefix.

Because the size of this structure is limited, we can only support a restricted number of properties.

It is not recommended to extend this structure, because exceeding those limits, might have unexpected effects!

The following list shows which properties are already defined:

The default material is using a multiple render target approach in fragment shaders.

This means it outputs values to multiple destination buffers.

Here is a quick example for extending the default material to setup your own shader material to create a vertex color material.

Gorilla.Material.VertexColor.pas

unit Gorilla.Material.VertexColor;
 
interface
 
uses
  System.SysUtils,
  System.Classes,
  FMX.Types,
  FMX.Types3D,
  FMX.Materials,
  FMX.MaterialSources,
  Gorilla.Material.Default;
 
type
  TGorillaVertexColorMaterial = class(TGorillaDefaultMaterial)
    protected
      procedure DoCreateVertexShader(); override;
      procedure DoCreateFragmentShader(); override;
 
    public
  end;
 
  TGorillaVertexColorMaterialSource = class(TGorillaDefaultMaterialSource)
    protected
      function CreateMaterial() : TMaterial; override;
 
    public
  end;
 
implementation
 
uses
  Gorilla.Material.Default.GLSL;
 
{ TGorillaVertexColorMaterial }
 
procedure TGorillaVertexColorMaterial.DoCreateVertexShader();
begin
  inherited;
 
  VertexShaderNode.AddDefine(GORILLA_GLSL_DEFINE_USE_COLOR);
  VertexShaderNode.RemoveDefine(GORILLA_GLSL_DEFINE_USE_TEXTURE);
end;
 
procedure TGorillaVertexColorMaterial.DoCreateFragmentShader();
begin
  inherited;
 
  FragmentShaderNode.AddDefine(GORILLA_GLSL_DEFINE_USE_COLOR);
  FragmentShaderNode.RemoveDefine(GORILLA_GLSL_DEFINE_USE_TEXTURE);
end;
 
{ TGorillaVertexColorMaterialSource }
 
function TGorillaVertexColorMaterialSource.CreateMaterial() : TMaterial;
begin
  Result := TGorillaVertexColorMaterial.Create(Self);
end;
 
end.

The default material allows to register more than one uniform buffer in shaders.

To create a new user-specific uniform buffer, you will need a representation of that structure in your default material class.

Notice: Structures inside of Delphi need a fixed alignment to OpenGL's std140 layout. Read more about OpenGL memory alignment here: https://www.khronos.org/opengl/wiki/Interface_Block_(GLSL)

At first we define a packed record structure inside of Delphi.

  PMyParams = ^TMyParams;
  TMyParams = packed record
    MyValue : Single;
    Reserved0 : Array[0..2] of Single; // taking care of memory alignment in TVector3D blocks.
 
    Point : TPoint3D;
    Reserved1 : Single; // taking care of memory alignment in TVector3D blocks.
  end;

The example above shows a structure declaration with memory alignment (Reserved0 + Reserved1). It should help to understand, how OpenGL aligns memory in std140 layout.

But in this exact case, we can optimize the record!

Because MyValue and Point fields fit into a single 4 * 4 Byte memory block of std140 alignment.

  PMyParams = ^TMyParams;
  TMyParams = packed record    
    Point : TPoint3D;
    MyValue : Single;
  end;

In GLSL the structure will appear as:

layout (binding=1, std140) uniform MyParams{
  vec3 _Point;
  float _MyValue;
};

In the next step, create a field inside of your material to store TMyParams.

TMyMaterial = class(TGorillaDefaultMaterial)
    protected
      FMyParams : TMyParams;
 
      /// override the update shader uniform buffers method to register our record in GPU.
      procedure DoUpdateShaderUniformBuffers(const Context: TContext3D;
        AProgram : TShaderProgram); override;
end;

And prepare values for shader:

constructor TMyMaterial.Create(const ASource : TGorillaDefaultMaterialSource);
begin
  inherited Create(ASource);
 
  FMyParams.MyValue := 0.25;
  FMyParams.Point := Point3D(1, -10, -1);
end;

Afterwards we implement our register function:

procedure TMyMaterial.DoUpdateShaderUniformBuffers(const Context: TContext3D;
  AProgram : TShaderProgram);
begin
  if not Assigned(AProgram) then
    Exit;
 
  inherited;
 
  /// let's register it in GPU shader.
  AProgram.RegisterUniformBuffer('MyParams', @FMyParams, SizeOf(FMyParams));
end;

In case we have dynamic values and need to modify the record values, we can use the DoApply() method. Because the memory is directly linked to the GPU, we can simply modify any value in our record and it will automatically be updated in shader.

procedure TGorillaWaterMaterial.DoApply(const Context: TContext3D);
begin
  inherited;
 
  FMyParams.MyValue := Random(100) / 100;
end;

Registering textures in shader is a little but different, but quite easy.

Because the default material manages a pool of textures, we only have to add a texture to it, and the component will do the rest for us.

Working further with our TMyMaterial, we need also a TMyMaterialSource to overwrite the protected DoCreateDefaultBitmaps() method.

type
  TMyMaterialSource = class(TGorillaMaterialSource)
    protected
      procedure DoCreateDefaultBitmaps(); override;
  end;
 
[...]
 
procedure TMyMaterialSource.DoCreateDefaultBitmaps();
var LEntry: TGorillaBitmapPoolEntry;
begin  
  ///
  /// adding new textures before calling "inherited"
  ///
  LEntry := DoAddOrUpdateBitmapToPool("MYTEXTURE0",
    TPixelFormatEx.RGBA8, TPixelFormatEx.RGBA, GORILLA_DEFAULT_TEXTURE_DATATYPE,
    false, true, true);
 
  /// in case you need to, modify the wrapping and filtering settings
  if Assigned(LEntry) then
    LEntry.SetExtendedProperties(
      TGorillaTextureWrap.Repeated, TGorillaTextureWrap.Repeated, TGorillaTextureWrap.Repeated,
      TTextureFilter.Linear, TTextureFilter.Linear);
 
  inherited;
 
  ///
  /// modifying default (existing) textures after calling "inherited".
  ///
  LEntry := Self.FindBitmapEntryByName(GORILLA_MATERIAL_TEXTURE_NORMALMAP);
  if Assigned(LEntry) then
    LEntry.SetExtendedProperties(
      TGorillaTextureWrap.Repeated, TGorillaTextureWrap.Repeated, TGorillaTextureWrap.Repeated,
      TTextureFilter.Linear, TTextureFilter.Linear);
end;

To add individual variables to the shaders you need to override the shader setup method.

Warning: This way adds a single variable to the shader and does not modify the uniform buffer!

Warning: Do not use this way to register texture variables! (Read more about in the section above.)

Then simply use the AddVariables() routine of the shader source:

Because variables need an incrementing index on registration, you need to supply the shader source specific variable:

Here is a short example:

procedure TGorillaMyMaterial.DoSetupFragmentShader();
begin
  inherited;
 
  // use the fragment shader source to add a new variable
  FFSShaderSource.AddVariables(
    [
    TContextShaderVariable.Create('MyPointF',
      TContextShaderVariableKind.Float2, FFSVarIndex, 0)
    ]);
 
  inc(FFSVarIndex, 1);
end;

In the next step you need to add a new uniforms node in the specific shader. To access the node builder in the material, use one of the following variables:

We add the new uniform node in the global uniform section of the node-tree to ensure, that is available anywhere in the code.

Take care to declare the variable name with the prefix “_”!

(Due to Firemonkey framework all uniform variables are declared by a leading underscore.)

procedure TGorillaMyMaterial.DoCreateFragmentShader();
var LUniform : TGorillaGLSLUniformsNode;
begin
  inherited;
 
  LUniform := TGorillaGLSLUniformsNode.Create(FragmentShaderNode);
  LUniform.AddDeclaration('_MyPointF', TGorillaShaderNodeVariableType.stVec2);
  FragmentShaderNode.Globals.Uniforms.Add(LUniform);
end;

You are allowed to add more than one variable in the uniforms node. There is no need to declare a single node for each variable.

To include a user specific function in shader source code, you need to declare a new node class inherited from TGorillaDeclarationNode. Then simply override the ToString() method and return your function declaration in shader language format.

In the DoCreateVertexShader() or DoCreateFragmentShader() function you create an instance of your declared node type and add it to the global function section of the node builder.

type
  TGorillaGLSLGetTextureColorFuncNode = class(TGorillaDeclarationNode)
    protected
    public
      function ToString() : String; override;
  end;
 
function TGorillaGLSLGetTextureColorFuncNode.ToString() : String;
begin
  Result := 'vec4 GetTextureColor(in sampler2D p_Texture, in vec2 p_TexCoord0){'#13#10 +
    '  return texture2D(p_Texture, p_TexCoord0);'#13#10 +
    '}'#13#10;
end;  
 
procedure TGorillaMyMaterial.DoCreateFragmentShader();
var LNode   : TGorillaNodeEntity;
begin
  // FragmentShaderNode is the fragment shader node builder
  LNode := TGorillaGLSLGetTextureColorFuncNode.Create(FragmentShaderNode);
  FragmentShaderNode.Globals.Functions.Add(LNode);
end;

After we've declared our user specific function, we want to call it in the shader. For that we need a new node. Here the basic class TGorillaNodeEntity is quite perfect for the job.

Afterwards we have to attach the node to the node-builder again. The insert point depends on the job to do, of course.

In our example we've written a function that returns the current texture color. This is called base-color. The default shader declares a local variable “LOCALS.BaseColor” for that. If we set this, it will automatically be used in the color-light-summary.

The entry point for this node operation is the surface-shader node in the fragment shader: “FragmentShaderNode.SurfaceShader”.

Caution: The problem here is, that there is already a node (TGorillaGLSLGetBaseColorNode) that computes the “LOCALS.BaseColor” value. So we need to replace it with our node. But we have to ensure the correct position in node hierarchy for a valid shader code output.

type
  TGorillaGLSLCallGetTextureColorNode = class(TGorillaNodeEntity)
    protected
    public
      function ToString() : String; override;
  end;
 
function TGorillaGLSLCallGetTextureColorNode.ToString() : String;
begin
  Result := 'LOCALS.BaseColor = GetTextureColor(_Texture0, l_TexCoord0);'#13#10;
end;
 
procedure TGorillaMyMaterial.DoCreateFragmentShader();
var LNode   : TGorillaNodeEntity;
    LOldIdx : Integer;
begin
  [...]
 
  LNode := TGorillaGLSLCallGetTextureColorNode.Create(FragmentShaderNode);
 
  /// replace base color request
  LOldIdx := FragmentShaderNode.SurfaceShader.IndexOf(TGorillaGLSLGetBaseColorNode, '');
  if (LOldIdx > -1) then
  begin
    /// remove old basecolor node
    FragmentShaderNode.SurfaceShader.Delete(LOldIdx);
    FragmentShaderNode.SurfaceShader.Insert(LOldIdx, LNode);
  end
  else FragmentShaderNode.SurfaceShader.Insert(0, LNode);
end;

Since 0.8.4 it's possible to modify your default shader at designtime, by using published properties *VertexShader* or *SurfaceShader*.

Simply select your default material source, go to object inspector and open the text editor of the property. An empty GLSL function should be visible depending on the shader used.

For VertexShader:

void VertexShader(inout TLocals DATA){
 
}

For SurfaceShader (Fragment/Pixel-Shader):

void SurfaceShader(inout TLocals DATA){
 
}

You can then modify or extend the shader functionality. Please have a look a the section Shader-Variables for the available fields in TLocals structure.

NOTICE: Modifying the vertex position in vertex-shader all 3 fields “DATA.Position”, “DATA.TransfVertexPos” and “DATA.WorldViewProjVertPos” need to be modified. Otherwise their basis might not be equal which leads to unexpected effects!

In the following example we've created a wobbling effect in the vertex shader:

vec2 DELPHI_HASH2(vec2 n){ 
    return fract(sin(n)*1399763.5453123);
}
 
float DELPHI_NOISE(vec2 st){
    vec2 i = floor(st);
    vec2 f = fract(st);
 
    vec2 u = f * f * (3.0 - 2.0 * f);
 
    float a = dot(DELPHI_HASH2(i + vec2(0.0,0.0)), f - vec2(0.0, 0.0));
    float b = dot(DELPHI_HASH2(i + vec2(1.0,0.0)), f - vec2(1.0, 0.0));
    float c = dot(DELPHI_HASH2(i + vec2(0.0,1.0)), f - vec2(0.0, 1.0));
    float d = dot(DELPHI_HASH2(i + vec2(1.0,1.0)), f - vec2(1.0, 1.0));
 
    return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
}
 
vec3 DELPHI_WOBBLE(vec3 pos, float time, float intensity){
    return vec3(pos.x, pos.y + (DELPHI_NOISE(vec2(pos.x, pos.z) + time) * intensity), pos.z);
}
 
void VertexShader(inout TLocals DATA){
  DATA.Position.xyz = DELPHI_WOBBLE(DATA.Position.xyz, _TimeInfo.y, 0.5);
 
  DATA.TransfVertexPos = _ModelMatrix * DATA.Position;
  DATA.WorldViewProjVertPos = _ModelViewProjectionMatrix * DATA.Position;
}

Default material component provides a few easy-to-use properties for automatic defines settings. By using the following properties in your default material, you can setup the necessary defines, your shaders need for computation.

constructor TMyMaterial.Create(const ASource : TGorillaDefaultMaterialSource);
begin
  inherited;
 
  UseTexturing := true;
  UseTexture0 := true;
  UseLighting := true;
  UseVertexColor := false;
end;