Animation

Gorilla3D provides a comprehensive animation system for bringing 3D scenes to life. The framework supports multiple animation types including skeletal/joint animation, vertex (mesh) animation, and property-based keyframe animation for transforming objects over time.

Animation Architecture

Key Components

TGorillaAnimationManager (Component)
└─ TGorillaAnimation Collection
   └─ TSkeletonKeyAnimation (Container)
      └─ TPropertyKeyAnimation instances
         ├─ TPoint3DKeyAnimation
         ├─ TVector3DKeyAnimation
         ├─ TQuaternion3DKeyAnimation
         ├─ TTransformationKeyAnimation
         └─ TCoordinateKeyAnimation

Animation Types

Gorilla3D supports several animation types:

Type Description Use Case
TPoint3DKeyAnimation Animates TPoint3D properties Position, rotation, scale transforms
TVector3DKeyAnimation Animates TVector3D properties Directional transforms
TQuaternion3DKeyAnimation Animates quaternion rotations Smooth rotations without gimbal lock
TTransformationKeyAnimation Animates full TMatrix3D transforms Skeletal/joint animation
TCoordinateKeyAnimation Animates vertex positions Mesh morphing, vertex animation
TSkeletonKeyAnimation Container for synchronized animations Character animation, complex rigs

Animation Manager

The TGorillaAnimationManager is the central component for managing all animations associated with a 3D model or character.

Basic Setup

A TGorillaAnimationManager instance will automatically be created, loading model data into a TGorillaModel component. The model component will take care of registering animations and setting up all necessary animations. Basically a TGorillaAnimationManager manages multiple TGorillaAnimation objects, which then hold multiple animation types.

Runtime

In special cases it might be needed to instanciate a TGorillaAnimationManager object manually. In order to do that, follow this workflow.

var
  Manager: TGorillaAnimationManager;
  Animation: TGorillaAnimation;
begin
  Manager := TGorillaAnimationManager.Create(Self);
  Manager.Mesh := GorillaModel1;

  // Load animation from definition
  Animation := TGorillaAnimation.CreateEx(Manager);
  Animation.LoadFromAnimationDef(AnimationDef);
  Manager.AddAnimation('Walk', Animation);
end;

Playing Animations

By Name

// Play a specific animation
Manager.PlayAnimation('Walk');

// Check current animation
if Manager.CurrentAnimationName = 'Run' then
  ShowMessage('Character is running');

By Instance

var
  WalkAnim: TGorillaAnimation;
begin
  WalkAnim := Manager.GetAnimation('Walk');
  if Assigned(WalkAnim) then
    Manager.PlayAnimation(WalkAnim);
end;

Sequential Playback

// Play next animation in sequence
Manager.PlayNextAnimation();

// Play previous animation
Manager.PlayPreviousAnimation();

Animation Control

// Get current animation
var CurrentAnim := Manager.Current;

if Assigned(CurrentAnim) then
begin
  // Start animation
  CurrentAnim.Start();

  // Stop animation
  CurrentAnim.Stop();

  // Reset to first frame
  CurrentAnim.Reset();

  // Adjust playback speed (1.0 = normal, 2.0 = double speed)
  CurrentAnim.SetSpeed(1.5);

  // Check animation state
  if CurrentAnim.IsRunning then
    ShowMessage('Animation playing');

  if CurrentAnim.IsPaused then
    ShowMessage('Animation paused');
end;

Property Key Animations

Property key animations allow you to animate specific properties of 3D objects using keyframes.

TPoint3DKeyAnimation

Animates TPoint3D properties like Position, Scale, or Rotation.

Basic Example

var
  Anim: TPoint3DKeyAnimation;
  Key0, Key1, Key2: TPoint3DKey;
begin
  Anim := TPoint3DKeyAnimation.Create(Self);
  Anim.PropertyName := 'Position.Point';
  Anim.Duration := 2.0;
  Anim.Loop := True;

  // Add element to animate
  Anim.AddElement(Cube1, True);

  // Define keyframes
  Key0 := TPoint3DKey(Anim.Keys.Add);
  Key0.Time := 0.0;
  Key0.Value[Cube1] := Point3D(0, 0, 0);

  Key1 := TPoint3DKey(Anim.Keys.Add);
  Key1.Time := 0.5;
  Key1.Value[Cube1] := Point3D(0, 5, 0);

  Key2 := TPoint3DKey(Anim.Keys.Add);
  Key2.Time := 1.0;
  Key2.Value[Cube1] := Point3D(0, 0, 0);

  Anim.Start();
end;

Animating Multiple Objects

// Single animation controlling multiple objects
Anim.AddElement(Cube1, True);
Anim.AddElement(Cube2, True);
Anim.AddElement(Sphere1, True);

// Set different values per object in each key
Key0 := TPoint3DKey(Anim.Keys.Add);
Key0.Time := 0.0;
Key0.Value[Cube1] := Point3D(0, 0, 0);
Key0.Value[Cube2] := Point3D(5, 0, 0);
Key0.Value[Sphere1] := Point3D(-5, 0, 0);

Animation Properties

// Interpolation type
Anim.Interpolation := TInterpolationType.Linear;
// Options: Linear, Quadratic, Cubic, Quartic, Quintic,
//          Sinusoidal, Exponential, Circular, Elastic, Back, Bounce

// Animation type (easing)
Anim.AnimationType := TAnimationType.InOut;
// Options: In, Out, InOut

// Looping and reversing
Anim.Loop := True;          // Repeat animation
Anim.AutoReverse := True;   // Reverse playback at end
Anim.Inverse := False;      // Start from end to beginning

// Timing
Anim.Delay := 0.5;          // Delay before starting (seconds)
Anim.Duration := 2.0;       // Total animation duration

TVector3DKeyAnimation

Animates TVector3D properties. Usage is identical to TPoint3DKeyAnimation:

var
  Anim: TVector3DKeyAnimation;
  Key: TVector3DKey;
begin
  Anim := TVector3DKeyAnimation.Create(Self);
  Anim.PropertyName := 'Scale';
  Anim.Duration := 1.0;

  Key := TVector3DKey(Anim.Keys.Add);
  Key.Time := 0.0;
  Key.Value[Cube1] := Vector3D(1, 1, 1);

  Key := TVector3DKey(Anim.Keys.Add);
  Key.Time := 1.0;
  Key.Value[Cube1] := Vector3D(2, 2, 2);

  Anim.Start();
end;

TQuaternion3DKeyAnimation

Animates rotations using quaternions for smooth interpolation without gimbal lock:

var
  Anim: TQuaternion3DKeyAnimation;
  Key: TQuaternion3DKey;
  Quat: TQuaternion3D;
begin
  Anim := TQuaternion3DKeyAnimation.Create(Self);
  Anim.PropertyName := 'RotationAngle';
  Anim.Duration := 3.0;
  Anim.Loop := True;

  // Create quaternions from Euler angles
  Quat := TQuaternion3D.Create(Vector3D(0, 0, 0));
  Key := TQuaternion3DKey(Anim.Keys.Add);
  Key.Time := 0.0;
  Key.Value[Cube1] := Quat;

  Quat := TQuaternion3D.Create(Vector3D(0, 180, 0));
  Key := TQuaternion3DKey(Anim.Keys.Add);
  Key.Time := 1.0;
  Key.Value[Cube1] := Quat;

  Anim.Start();
end;

TTransformationKeyAnimation

Animates full transformation matrices, primarily used for skeletal animation:

var
  Anim: TTransformationKeyAnimation;
  Key: TTransformationKey;
  Matrix: TMatrix3D;
begin
  Anim := TTransformationKeyAnimation.Create(Self);
  Anim.PropertyName := 'LocalMatrix';
  Anim.AddElement(Joint1, True);

  Key := TTransformationKey(Anim.Keys.Add);
  Key.Time := 0.0;
  Matrix := TMatrix3D.CreateTranslation(Point3D(0, 0, 0));
  Key.Value[Joint1] := Matrix;

  Key := TTransformationKey(Anim.Keys.Add);
  Key.Time := 1.0;
  Matrix := TMatrix3D.CreateTranslation(Point3D(0, 5, 0)) *
            TMatrix3D.CreateRotationY(DegToRad(45));
  Key.Value[Joint1] := Matrix;

  Anim.Start();
end;

Skeletal Animation

Skeletal (or armature) animation uses bones/joints to deform a mesh. This is the standard approach for character animation.

TSkeletonKeyAnimation

TSkeletonKeyAnimation is a container that synchronizes multiple TPropertyKeyAnimation instances:

var
  SkeletonAnim: TSkeletonKeyAnimation;
  Joint1Anim, Joint2Anim: TTransformationKeyAnimation;
begin
  SkeletonAnim := TSkeletonKeyAnimation.Create(Self);
  SkeletonAnim.Duration := 2.0;
  SkeletonAnim.Loop := True;
  SkeletonAnim.AutoRepaint := True;  // Auto-update viewport

  // Create joint animations
  Joint1Anim := TTransformationKeyAnimation.Create(Self);
  Joint1Anim.PropertyName := 'LocalMatrix';
  Joint1Anim.AddElement(ArmJoint, True);
  // ... add keys for Joint1Anim

  Joint2Anim := TTransformationKeyAnimation.Create(Self);
  Joint2Anim.PropertyName := 'LocalMatrix';
  Joint2Anim.AddElement(LegJoint, True);
  // ... add keys for Joint2Anim

  // Add to skeleton container
  SkeletonAnim.AddInterpolator(Joint1Anim);
  SkeletonAnim.AddInterpolator(Joint2Anim);

  // Start synchronized animation
  SkeletonAnim.Start();
end;

Skeleton Animation Control

// Start all joint animations together
SkeletonAnim.Start();

// Stop all
SkeletonAnim.Stop();

// Reset to first frame
SkeletonAnim.Reset();

// Adjust speed for all joints
SkeletonAnim.SetSpeed(0.5);  // Half speed

// Access individual interpolators
for var Interpolator in SkeletonAnim.Interpolators do
begin
  ShowMessage(Interpolator.PropertyName);
end;

AutoRepaint

The AutoRepaint property controls viewport updates:

// Automatic viewport repaint (default)
SkeletonAnim.AutoRepaint := True;

// Manual control for better performance
SkeletonAnim.AutoRepaint := False;
GorillaViewport1.BeginUpdate();
try
  SkeletonAnim.Start();
  // ... perform other operations
finally
  GorillaViewport1.EndUpdate();
end;

Vertex Animation

Vertex (or mesh) animation directly modifies mesh vertices over time, useful for organic deformations and morph targets.

TCoordinateKeyAnimation

var
  Anim: TCoordinateKeyAnimation;
  Key: TCoordinateKey;
  Vertices: TPoint3DDynArray;
begin
  Anim := TCoordinateKeyAnimation.Create(Self);
  Anim.PropertyName := 'Data.Vertices';
  Anim.Duration := 2.0;
  Anim.Loop := True;
  Anim.AddElement(CustomMesh1, True);

  // Key 0: Original vertices
  Key := TCoordinateKey(Anim.Keys.Add);
  Key.Time := 0.0;
  SetLength(Vertices, 8);
  Vertices[0] := Point3D(-1, -1, -1);
  Vertices[1] := Point3D( 1, -1, -1);
  // ... set all vertices
  Key.Vertices[CustomMesh1] := Vertices;

  // Key 1: Deformed vertices
  Key := TCoordinateKey(Anim.Keys.Add);
  Key.Time := 1.0;
  Vertices[0] := Point3D(-1.5, -1, -1);
  Vertices[1] := Point3D( 1.5, -1, -1);
  // ... set deformed vertices
  Key.Vertices[CustomMesh1] := Vertices;

  Anim.Start();
end;

Loading Animations from Files

Animations are typically imported from 3D model files (G3D, DAE or FBX) using animation definitions.

It is not a recommended process, but good for understanding the structures behind.

var
  Loader: TGorillaLoader;
  ModelDef: TModelDef;
  AnimDef: TAnimationDef;
  Animation: TGorillaAnimation;
begin
  Loader := TGorillaLoader.Create();
  try
    // Load model with animations
    ModelDef := Loader.LoadUndefinedModelDefFromFile(nil, 'character.fbx');

    // You need to setup FMX models and meshes, otherwise LoadFromAnimationDef
    // may find references objects not.

    // Iterate through embedded animations
    for AnimDef in ModelDef.Animations do
    begin
      Animation := TGorillaAnimation.CreateEx(AnimationManager1);
      Animation.LoadFromAnimationDef(AnimDef);

      // Add to manager
      AnimationManager1.AddAnimation(AnimDef.Id, Animation);
    end;
  finally
    Loader.Free();
  end;
end;

Animation Transformation

Transform animations for mirroring or custom modifications:

var
  MirrorMatrix: TMatrix3D;
begin
  // Create mirror matrix (flip on X axis)
  MirrorMatrix := TMatrix3D.CreateScaling(Point3D(-1, 1, 1));

  // Transform all keys in animation
  Animation.Skeleton.Transform(MirrorMatrix);
end;

Animation Caching

For performance optimization, Gorilla3D can cache animated frames:

Frame Caching

// Enable caching during import
Animation.LoadFromAnimationDef(AnimDef);

// Get cached frame for rendering
var
  MeshBuffer: TMeshBufferObject;
begin
  MeshBuffer := Animation.GetCurrentCachedFrame(MeshDef);
  if Assigned(MeshBuffer) then
  begin
    // Render cached frame
  end;
end;

Fixed Frame Debugging

// Set specific frame for debugging
Animation.SetFixedCacheFrame(15);  // Show frame 15

// Release fixed frame
Animation.UnsetFixedCacheFrame();

Frame Information

// Get animation frame info
ShowMessage(Format('Frames: %d, FPS: %d', [
  Animation.FrameCount,
  Animation.FrameRate
]));

Force Stepping

Force animation updates outside the normal FMX message loop for smoother playback:

// In your main rendering loop or timer
if TGorillaAnimationManager.ForceStep(0.01) then
  GorillaViewport1.EndUpdate()
else
  GorillaViewport1.EndUpdateWithoutInvalidate();

Parameters:

  • AMinDeltaTime: Minimum time (seconds) since last forced update (default: 0.01)

Returns: True if step was forced and viewport needs updating

Animation Events

React to animation progress:

procedure TForm1.AnimationProcess(Sender: TObject);
begin
  // Called on each animation frame
  ProgressBar1.Value := Animation.Skeleton.NormalizedTime * 100;
end;

procedure TForm1.AnimationFinish(Sender: TObject);
begin
  // Called when animation completes
  ShowMessage('Animation finished');
end;

// Assign events
Animation.Skeleton.OnProcess := AnimationProcess;
Animation.Skeleton.OnFinish := AnimationFinish;

Simple Property Animation

For simple property animations without keyframes, use TPoint3DAnimation:

var
  Anim: TPoint3DAnimation;
begin
  Anim := TPoint3DAnimation.Create(Self);
  Anim.Parent := Cube1;
  Anim.PropertyName := 'Position.Point';
  Anim.StartValue.Point := Point3D(0, 0, 0);
  Anim.StopValue.Point := Point3D(10, 0, 0);
  Anim.Duration := 2.0;
  Anim.StartFromCurrent := True;
  Anim.Start();
end;

Best Practices

  1. Use Skeleton Animation for Characters: Group related joint animations in TSkeletonKeyAnimation for synchronized playback

  2. Cache Complex Animations: Enable frame caching for CPU-intensive vertex animations

  3. Control AutoRepaint: Disable AutoRepaint and manually control viewport updates for better performance

  4. Use Quaternions for Rotation: TQuaternion3DKeyAnimation provides smoother rotation than Euler angles

  5. Optimize Keyframe Count: Use only necessary keyframes; interpolation handles in-between frames

  6. Force Stepping for Smoothness: Use ForceStep() in rendering loops to avoid FMX timer jitter

  7. Check Animation State: Always verify IsRunning before operations that depend on active animation

  8. Proper Cleanup: Always stop animations before destroying animated objects

  9. Use Animation Manager: Centralize animation control through TGorillaAnimationManager

  10. Test Playback Speed: Adjust animation speed based on target platform performance

Common Patterns

Continuous Rotation

procedure CreateRotationAnimation(AObject: TControl3D);
var
  Anim: TPoint3DKeyAnimation;
  Key: TPoint3DKey;
begin
  Anim := TPoint3DKeyAnimation.Create(AObject);
  Anim.PropertyName := 'RotationAngle.Point';
  Anim.Duration := 4.0;
  Anim.Loop := True;
  Anim.Interpolation := TInterpolationType.Linear;

  Key := TPoint3DKey(Anim.Keys.Add);
  Key.Time := 0.0;
  Key.Value[AObject] := Point3D(0, 0, 0);

  Key := TPoint3DKey(Anim.Keys.Add);
  Key.Time := 1.0;
  Key.Value[AObject] := Point3D(0, 360, 0);

  Anim.Start();
end;

Bounce Effect

Anim := TPoint3DKeyAnimation.Create(Self);
Anim.PropertyName := 'Position.Point';
Anim.Interpolation := TInterpolationType.Bounce;
Anim.AnimationType := TAnimationType.Out;
Anim.Duration := 1.0;
// ... add keys
Anim.Start();

Ping-Pong Animation

Anim := TPoint3DKeyAnimation.Create(Self);
Anim.Loop := True;
Anim.AutoReverse := True;  // Plays forward then backward
// ... configure and start

Troubleshooting

Animation Not Playing

// Check animation is enabled
if not Animation.Skeleton.Enabled then
  Animation.Skeleton.Enabled := True;

// Verify parent is set
if not Assigned(Animation.Parent) then
  Animation.Parent := SomeContainer;

// Check duration is set
if Animation.Skeleton.Duration = 0 then
  Animation.Skeleton.Duration := 2.0;

Jerky Playback

// Use ForceStep for smoother updates
TGorillaAnimationManager.ForceStep(0.01);

// Or adjust interpolation
Animation.Skeleton.Interpolation := TInterpolationType.Cubic;

Animation Too Fast/Slow

// Adjust speed
Animation.SetSpeed(0.5);  // Half speed
Animation.SetSpeed(2.0);  // Double speed

Memory Issues with Vertex Animation

// Enable caching to reduce real-time computation
// Ensure proper cleanup of cached frames

See Also