Gorilla.Mesh Unit Reference

Overview

The Gorilla.Mesh unit provides the core mesh component for Gorilla3D rendering. It contains the TGorillaMesh class, which represents individual 3D meshes with geometry data, materials, and rendering capabilities. Each mesh within a TGorillaModel is an instance of TGorillaMesh.

Classes

TGorillaMesh

Default Gorilla3D mesh control. Can be used as standalone component or child of TGorillaModel. Each mesh inside a model is a TGorillaMesh instance.

Inheritance: TGorillaTransform → TGorillaMesh

Platforms: All Gorilla3D supported platforms (Windows, macOS, Linux, Android, iOS)

Public Properties

Property Type Description
Model TGorillaControl Get or set parent model component holding reference to mesh instance.
ReferencedName String Reference name for identifying mesh explicitly.
MeshData TMeshData Returns internal mesh data object with vertex and indices buffers. May be empty if mesh is STATIC for memory savings.
VertexJoints TVertexJointsList Returns used vertex joints list for skeletal animation.
Meshes TGorillaMeshList Returns list of sub-meshes.
Coordinates TPoint3DDynArray Get or set vertex coordinates array.
Vertices TVertexDataMap Get or set vertex data map containing all vertex attributes.
IsStatic Boolean Get or set static mesh flag. Static meshes prebuffer vertex data to GPU, clearing CPU memory.
WrapMode TMeshWrapMode Get or set mesh wrap mode for texture coordinates.
FlatShading Boolean Enable or disable flat shading. Recalculates normals per-face instead of per-vertex.

Published Properties

Property Type Default Description
MaterialSource TMaterialSource nil Get or set material source for mesh rendering.
Shadows Boolean False Whether this mesh receives cascaded shadows. Setting True flips the linked default material(s) to ShadowMethod = CascadedShadowMapping and propagates to all sub-meshes.
CastShadows Boolean True Whether this mesh is rendered into the cascaded-shadow depth atlas as a caster. Set False to keep an object from throwing a shadow — e.g. a water surface or transparent wall that sits between the light and the scene and would otherwise shadow everything beneath it. Independent of Shadows.
Wireframe Boolean False Enable wireframe rendering (performance intensive, debugging only).
WireframeMaterial TMaterialSource nil Material source for wireframe rendering in post-processing.
ShowNormals Boolean False Enable normal visualization (performance intensive).
NormalsColor TAlphaColor - Color for rendered normals if ShowNormals is active.
Instances TGorillaMeshInstances - Collection managing mesh instances for GPU instancing.
Materials TGorillaMeshMaterialCollection - Read-only design-time collection showing linked material sources.
Behaviours TGorillaMeshBehaviourCollection - Collection of material behaviours attached to mesh.
MeshCollection TGorillaMeshCollection - Read-only design-time collection showing submeshes.

Standard properties: Width, Height, Depth, Position, Scale, RotationAngle, Visible, Opacity, etc.

Constructor & Destructor

constructor Create(AOwner: TComponent); override;
destructor Destroy(); override;

Public Methods

Geometry Access
function GetBoundingBox(): TBoundingBox; override;

Returns absolute bounding box with applied mesh and local matrices.


Instancing
function GetInstance(AIndex: Integer): TMatrix3D;
procedure SetInstance(AIndex: Integer; const AValue: TMatrix3D);

Get or set transformation matrix for specific instance by index.

Example:

// Modify instance position
var Transform := Mesh.GetInstance(0);
Transform := Transform * TMatrix3D.CreateTranslation(Point3D(10, 0, 0));
Mesh.SetInstance(0, Transform);

Ray Casting and Triangle Picking
function RayCastIntersect(const ARayPos, ARayDir: TPoint3D;
  var AIntersection, ANormal: TPoint3D): Boolean; reintroduce;

Performs ray cast intersection test on this mesh using absolute ray position and direction. Returns TRUE if ray intersects any triangle, with intersection point and normal vector at that position. Searches entire mesh hierarchy including all submeshes.

Important: Requires absolute world-space ray position and direction vectors.

Example:

var
  RayPos, RayDir: TPoint3D;
  Intersection, Normal: TPoint3D;
begin
  // Absolute world-space ray
  RayPos := Point3D(0, 10, 0);
  RayDir := Point3D(0, -1, 0);  // Downward

  if Mesh.RayCastIntersect(RayPos, RayDir, Intersection, Normal) then
  begin
    ShowMessage('Hit at: ' + Intersection.ToString);
    ShowMessage('Normal: ' + Normal.ToString);
  end;
end;

function PickTriangle(const X, Y: Single;
  var AIntersection, ANormal: TPoint3D; out A, B, C: TPoint3D): Boolean; overload;

Detects intersected triangle using screen coordinates (X, Y in pixels). Converts screen coordinates to 3D ray and performs intersection test. Returns TRUE if triangle hit, providing intersection point, normal, and absolute triangle corner coordinates (A, B, C).

Parameters:

  • X, Y - Screen coordinates in pixels
  • AIntersection - Output: 3D intersection point (world space)
  • ANormal - Output: Surface normal at intersection
  • A, B, C - Output: Triangle corner positions (world space)

Example:

var
  Intersection, Normal: TPoint3D;
  A, B, C: TPoint3D;
begin
  // Mouse click at screen position
  if Mesh.PickTriangle(MouseX, MouseY, Intersection, Normal, A, B, C) then
  begin
    ShowMessage('Triangle hit at: ' + Intersection.ToString);
    ShowMessage(Format('Triangle corners: [%s, %s, %s]',
      [A.ToString, B.ToString, C.ToString]));
  end;
end;

function PickTriangle(const X, Y: Single;
  var AResult: TTriangleRayCastResult): Boolean; overload;

Detects intersected triangle using screen coordinates and returns comprehensive result structure. Provides intersection point, normal, triangle corners, distance, and reference to intersected object.

Parameters:

  • X, Y - Screen coordinates in pixels
  • AResult - Output: Complete ray cast result structure

Example:

var
  Result: TTriangleRayCastResult;
begin
  if Mesh.PickTriangle(MouseX, MouseY, Result) then
  begin
    ShowMessage(Format('Hit at distance: %.2f', [Result.T]));
    ShowMessage('Point: ' + Result.Intersection.ToString);
    ShowMessage('Normal: ' + Result.Normal.ToString);

    // Access triangle corners
    ShowMessage(Format('Triangle: [%s, %s, %s]',
      [Result.Triangle[0].ToString,
       Result.Triangle[1].ToString,
       Result.Triangle[2].ToString]));

    // Check intersected object
    if Assigned(Result.Instance) then
      ShowMessage('Hit object: ' + TComponent(Result.Instance).Name);
  end;
end;

function PickTriangle(const ARayPos, ARayDir: TVector3D;
  var AIntersection, ANormal: TPoint3D; out A, B, C: TPoint3D): Boolean; overload;

Detects intersected triangle using absolute ray position and direction. Returns intersection point, normal, and triangle corner coordinates.

Important: Requires absolute world-space ray vectors.

Parameters:

  • ARayPos - Absolute ray start position (world space)
  • ARayDir - Absolute ray direction vector (world space)
  • AIntersection - Output: 3D intersection point
  • ANormal - Output: Surface normal at intersection
  • A, B, C - Output: Triangle corner positions

Example:

var
  RayPos, RayDir: TVector3D;
  Intersection, Normal: TPoint3D;
  A, B, C: TPoint3D;
begin
  // Setup ray from camera position
  RayPos := Vector3D(Camera.Position.X, Camera.Position.Y, Camera.Position.Z);
  RayDir := Vector3D(0, 0, 1);  // Forward

  if Mesh.PickTriangle(RayPos, RayDir, Intersection, Normal, A, B, C) then
  begin
    // Process triangle intersection
    ShowMessage('Triangle hit!');
  end;
end;

function PickTriangle(const ARayPos, ARayDir: TVector3D;
  var AResult: TTriangleRayCastResult): Boolean; overload;

Detects intersected triangle using absolute ray position and direction and returns comprehensive result structure.

Important: Requires absolute world-space ray vectors.

Parameters:

  • ARayPos - Absolute ray start position (world space)
  • ARayDir - Absolute ray direction vector (world space)
  • AResult - Output: Complete ray cast result structure

Example:

var
  Result: TTriangleRayCastResult;
  RayPos, RayDir: TVector3D;
begin
  RayPos := Vector3D(0, 100, 0);
  RayDir := Vector3D(0, -1, 0);  // Downward ray

  if Mesh.PickTriangle(RayPos, RayDir, Result) then
  begin
    ShowMessage(Format('Hit at distance: %.2f units', [Result.T]));
    ShowMessage('Intersection: ' + Result.Intersection.ToString);
    ShowMessage('Normal: ' + Result.Normal.ToString);

    // Calculate impact details
    var ImpactForce := 100.0 / Result.T;  // Force based on distance
  end;
end;

Material Management
procedure ApplyMaterialSource(AValue: TMaterialSource);

Applies material source to mesh and all submeshes recursively.


Utility Methods
procedure ComputeTangentsAndBinormals();

Computes tangent and binormal vectors for normal mapping. Called automatically when needed.


procedure BuildTriangleMesh();

Debugging routine creating simple triangle in mesh data. Deletes existing data.


Helper Classes

TGorillaMeshInstances

Collection managing mesh instances for GPU instancing.

Inheritance: TOwnedCollection → TGorillaMeshInstances

Properties

Property Type Description
OwnerMesh TGorillaMesh Returns owning mesh component.
CacheUpdated Boolean Indicates if instance cache was updated.
CachedInstancesPtr PMatrix3D Pointer to cached instances array.
CachedInstancesCount Integer Number of cached instances.

Methods

function AddInstance(const ATransform: TMatrix3D; const ACreateItem: Boolean;
  AName: String = ''): Integer;

Add new instance to collection. For runtime, reduce memory by setting ACreateItem to false.

Example:

// Add instances without creating collection items (memory efficient)
for var x := 0 to 9 do
  for var z := 0 to 9 do
  begin
    var Transform := TMatrix3D.CreateTranslation(Point3D(x * 2, 0, z * 2));
    Mesh.Instances.AddInstance(Transform, False);
  end;

function GetInstance(AIndex: Integer): TMatrix3D;
procedure SetInstance(AIndex: Integer; const AValue: TMatrix3D);

Get or update specific instance transformation by index.


function DeleteInstance(AIndex: Integer): Boolean;

Delete specific instance by index. Adjusts cache accordingly. Returns success.


procedure ClearInstances();

Clears all items and cached instances.


procedure UpdateInstanceCache(); overload;
procedure UpdateInstanceCache(const ABaseTransform: TMatrix3D;
  const AInstances: TArray<TMatrix3D>); overload;

Updates internal instance cache for GPU rendering.


function ToArray(): TArray<TMatrix3D>;

Returns instances as array of transformation matrices.


TGorillaMeshInstance

Individual mesh instance with transform properties.

Inheritance: TCollectionItem → TGorillaMeshInstance

Published Properties

Property Type Description
DisplayName String Instance display name.
Position TPosition3D Instance position.
Scale TPosition3D Instance scale.
RotationAngle TPosition3D Instance rotation angles.
RotationCenter TPosition3D Instance rotation center.

Public Properties

Property Type Description
Transform TMatrix3D Computed transformation matrix.
OwnerMesh TGorillaMesh Returns owning mesh.

Methods

procedure UpdateTransform();
procedure SetTransform(const ATransform: TMatrix3D);
procedure ResetRotationAngle();

TGorillaMeshMaterialCollection

Read-only design-time collection showing linked material sources.

Inheritance: TGorillaReadOnlyCollection → TGorillaMeshMaterialCollection

Methods

class procedure Update(ACollection: TGorillaMeshMaterialCollection;
  AMesh: TGorillaMesh); reintroduce;

Updates collection to reflect current mesh materials.


function MaterialExists(AMaterial: TMaterialSource): Boolean;

Checks if material exists in collection.


TGorillaMeshCollection

Read-only design-time collection showing submeshes.

Inheritance: TGorillaReadOnlyCollection → TGorillaMeshCollection

Methods

class procedure Update(ACollection: TGorillaMeshCollection;
  AMesh: TGorillaMesh); reintroduce;

Updates collection to reflect current submeshes.


function MeshExists(AMesh: TGorillaMesh): Boolean;

Checks if mesh exists in collection.


TGorillaMeshBehaviourCollection

Collection managing material behaviours attached to mesh.

Inheritance: TGorillaReadOnlyCollection → TGorillaMeshBehaviourCollection

Methods

class procedure Update(ACollection: TGorillaMeshBehaviourCollection;
  AMesh: TGorillaMesh); reintroduce;

Updates collection to reflect current behaviours.


function BehaviourExists(ABehaviour: TGorillaMaterialBehaviour): Boolean;

Checks if behaviour exists in collection.


Helper Types

TGorillaMeshList

List of TGorillaMesh instances.

TGorillaMeshList = TObjectList<TGorillaMesh>;

TVertexJointsList

List managing vertex joint information for skeletal animation.

Usage Examples

Creating a Mesh

var
  Mesh: TGorillaMesh;
begin
  Mesh := TGorillaMesh.Create(Self);
  Mesh.Parent := Viewport;
  Mesh.MaterialSource := MyMaterial;
end;

GPU Instancing

var
  Mesh: TGorillaMesh;
  Transform: TMatrix3D;
begin
  Mesh := TGorillaMesh.Create(Self);
  Mesh.Parent := Viewport;

  // Add 100 instances
  for var i := 0 to 99 do
  begin
    Transform := TMatrix3D.CreateTranslation(
      Point3D(Random(100) - 50, 0, Random(100) - 50)
    );
    Mesh.Instances.AddInstance(Transform, False);  // No collection item = memory efficient
  end;
end;

Accessing Sub-Meshes

// Iterate through all submeshes
for var i := 0 to Mesh.Meshes.Count - 1 do
begin
  var SubMesh := Mesh.Meshes[i];
  ShowMessage('SubMesh: ' + SubMesh.Name);

  // Apply material to submesh
  SubMesh.MaterialSource := BodyMaterial;
end;

Static Mesh Optimization

// Mark mesh as static for better performance
Mesh.IsStatic := True;

// Static meshes prebuffer to GPU and clear CPU memory
// Use for meshes that never change geometry

Flat Shading

// Enable flat shading for hard-edge look
Mesh.FlatShading := True;

// Normals recalculated per-face instead of per-vertex

Wireframe Rendering

Mesh.Wireframe := True;
Mesh.WireframeMaterial := WireframeMaterialSource;

// Warning: Performance intensive, use for debugging only

Normal Visualization

Mesh.ShowNormals := True;
Mesh.NormalsColor := TAlphaColors.Green;

// Shows normal directions for debugging

Ray Casting and Triangle Picking

Using RayCastIntersect

var
  RayPos, RayDir: TPoint3D;
  Intersection, Normal: TPoint3D;
begin
  // Absolute world-space ray
  RayPos := Point3D(0, 10, 0);
  RayDir := Point3D(0, -1, 0);  // Downward

  if Mesh.RayCastIntersect(RayPos, RayDir, Intersection, Normal) then
  begin
    ShowMessage('Hit at: ' + Intersection.ToString);
    ShowMessage('Surface normal: ' + Normal.ToString);
  end;
end;

Using PickTriangle with Screen Coordinates

procedure TForm1.Viewport1MouseDown(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Single);
var
  Intersection, Normal: TPoint3D;
  A, B, C: TPoint3D;
begin
  // Pick triangle at mouse position
  if Mesh.PickTriangle(X, Y, Intersection, Normal, A, B, C) then
  begin
    ShowMessage('Clicked on mesh at: ' + Intersection.ToString);
    ShowMessage(Format('Triangle corners: [%s, %s, %s]',
      [A.ToString, B.ToString, C.ToString]));

    // Visualize hit point
    Sphere.Position.Point := Intersection;
  end;
end;

Using PickTriangle with Result Structure

procedure TForm1.Viewport1MouseDown(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Single);
var
  Result: TTriangleRayCastResult;
begin
  if Mesh.PickTriangle(X, Y, Result) then
  begin
    ShowMessage(Format('Hit at distance: %.2f units', [Result.T]));
    ShowMessage('Intersection: ' + Result.Intersection.ToString);
    ShowMessage('Normal: ' + Result.Normal.ToString);

    // Access all triangle corners
    for var i := 0 to 2 do
      ShowMessage(Format('Corner %d: %s', [i, Result.Triangle[i].ToString]));

    // Check which object was hit
    if Assigned(Result.Instance) then
    begin
      if Result.Instance is TGorillaMesh then
        ShowMessage('Hit mesh: ' + TGorillaMesh(Result.Instance).Name);
    end;
  end;
end;

Using PickTriangle with Absolute Ray

var
  Result: TTriangleRayCastResult;
  RayPos, RayDir: TVector3D;
begin
  // Cast ray from above downward
  RayPos := Vector3D(Character.Position.X, 100, Character.Position.Z);
  RayDir := Vector3D(0, -1, 0);

  if Mesh.PickTriangle(RayPos, RayDir, Result) then
  begin
    // Found ground height
    var GroundHeight := Result.Intersection.Y;
    Character.Position.Y := GroundHeight + 1.0;  // Place character on ground

    ShowMessage(Format('Ground found at height: %.2f', [GroundHeight]));
  end;
end;

Modifying Instances

// Animate instances
for var i := 0 to Mesh.Instances.CachedInstancesCount - 1 do
begin
  var Transform := Mesh.Instances.GetInstance(i);

  // Rotate instance
  Transform := Transform * TMatrix3D.CreateRotationY(0.01);

  Mesh.Instances.SetInstance(i, Transform);
end;

// Update cache after modifications
Mesh.Instances.UpdateInstanceCache();

Accessing Vertex Data

// Get vertex positions
var Coords := Mesh.Coordinates;
for var i := Low(Coords) to High(Coords) do
  ShowMessage(Coords[i].ToString);

// Warning: Static meshes may have empty vertex data on CPU
if not Mesh.IsStatic then
begin
  // Modify vertices
  var Vertices := Mesh.Vertices;
  // ... modify vertex data ...
  Mesh.Vertices := Vertices;
end;

Material Management

// Apply material to mesh and all submeshes
Mesh.ApplyMaterialSource(MyMaterial);

// Apply to specific mesh only
Mesh.MaterialSource := MyMaterial;

Constants

Mesh Defaults

GORILLA_POLYGON_MAXSIZE = 16;  // Maximum polygon size

Usage Notes

  1. Static Meshes: Set IsStatic = True for meshes with unchanging geometry to improve performance and reduce memory.

  2. GPU Instancing: Use AddInstance with ACreateItem = False for memory-efficient instancing at runtime.

  3. Wireframe/Normals: Both features are performance intensive. Use for debugging only.

  4. Flat Shading: Recalculates normals per-face. Use for hard-edge modeling style.

  5. Sub-Meshes: Complex models contain mesh hierarchies. Iterate through Meshes collection to access all parts.

  6. Vertex Data Access: Static meshes may have empty CPU vertex data. Check IsStatic before accessing.

  7. Ray Casting and Triangle Picking:

    • Use RayCastIntersect for absolute world-space ray tests
    • Use PickTriangle with screen coordinates (X, Y) for mouse interaction
    • Use PickTriangle with absolute ray for custom ray tests
    • All methods perform deep search on entire mesh hierarchy including submeshes
    • TTriangleRayCastResult provides complete intersection details including distance, normal, triangle corners, and intersected object reference

See Also