Camera

Cameras in Gorilla3D control the viewpoint and projection of your 3D scene. The framework provides TGorillaCamera for basic camera functionality and TGorillaSmoothCameraController for interactive, smooth camera navigation.

TGorillaCamera

TGorillaCamera extends FireMonkey's TCamera with additional Gorilla3D-specific features and better integration with the rendering pipeline.

Creating a Camera

Design-Time

  1. Drop a TGorillaCamera onto your viewport from the tool palette
  2. Set it as the active camera in the viewport's Camera property
  3. Deactivate the design time camera by Viewport.UsingDesignCamera := False;
  4. Configure position and field of view as needed

Runtime

var
  Camera: TGorillaCamera;
begin
  Camera := TGorillaCamera.Create(Viewport);
  Camera.Parent := Viewport;
  Camera.Position.Z := -10;
  Camera.FOV := 45;

  Viewport.Camera := Camera;
  Viewport.UsingDesignCamera := False;
end;

Field of View

The field of view (FOV) controls how wide the camera's perspective is:

// Narrow FOV (zoomed in)
Camera.FOV := 30;

// Standard FOV
Camera.FOV := 45;

// Wide angle FOV
Camera.FOV := 75;

Guidelines:

  • 30-40°: Telephoto lens effect, good for portraits
  • 45-60°: Standard perspective, most natural
  • 70-90°: Wide angle, good for interiors or expansive scenes
  • >90°: Fish-eye effect

Camera Positioning

// Set position directly
Camera.Position.Point := Point3D(0, 5, -10);

// Or use individual components
Camera.Position.X := 0;
Camera.Position.Y := 5;
Camera.Position.Z := -10;

// Set rotation
Camera.RotationAngle.Point := Point3D(15, 0, 0);

Target Focus

In case you want to always focus a specific 3D element, you can set the Target property of your TCamera/TGorillaCamera component. It will automatically adjust the camera's rotation to it.

TGorillaSmoothCameraController

The smooth camera controller provides interactive camera navigation with physics-based movement, perfect for viewers, object inspectors, and interactive 3D applications.

Basic Setup

Design-Time Setup

Every TGorillaViewport component has a built-in smooth camera controller, which you can access by GorillaViewport1.GetDesignCameraController() This is also the default setup and default navigation available if you do not overwrite with your own camera settings.

You can modify the design camera controller at runtime, f.e. to increase movement speed.

with GorillaViewport1.GetDesignCameraController() do
begin
  // Change the kind of mouse and keyboard inputs to control the camera
  NavigationProfile := TGorillaCameraNavigationProfile.cnpOrbit;

  // Timer interval for updating camera position
  Interval := 10;

  // Intensity values to control navigation speed
  ShiftIntensity := 5;
  IntensityZoom := 15;
  IntensityRotate := 20;
  IntensityUpAndDown := 5;
end;

Runtime Setup

var
  Controller: TGorillaSmoothCameraController;
  Camera: TGorillaCamera;
begin
  // Create controller
  Controller := TGorillaSmoothCameraController.Create(Viewport);
  Controller.Parent := Viewport;
  Controller.Position.Point := Point3D(0, 0, 0);

  // Create camera as child
  Camera := TGorillaCamera.Create(Controller);
  Camera.Parent := Controller;
  Camera.Position.Z := -10;  // Distance from target

  // Link them
  Controller.Camera := Camera;
  Controller.Viewport := Viewport;
  Controller.Enabled := True;
end;

Navigation Profiles

Choose a preset profile for familiar navigation:

// Default profile (no orbiting)
Controller.NavigationProfile := cnpDefault;
// - Rotate: Left mouse button
// - Shift XZ: Right mouse button
// - Shift XY: Shift + Right mouse button
// - Zoom: Mouse wheel

// Orbit profile
Controller.NavigationProfile := cnpOrbit;
// - Rotate: Right mouse button (orbits around target)
// - Shift XY: Left mouse button
// - Shift XZ: Shift + Left mouse button
// - Zoom: Mouse wheel

// Blender-like profile
Controller.NavigationProfile := cnpBlender;
// - Rotate: Ctrl + Right mouse button (orbits)
// - Shift XY: Ctrl + Left mouse button
// - Shift XZ: Shift + Left mouse button
// - Zoom: Mouse wheel

// Sketchfab-like profile
Controller.NavigationProfile := cnpSketchfab;
// - Rotate: Left mouse button (orbits)
// - Shift XY: Right mouse button
// - Shift XZ: Shift + Right mouse button
// - Move forward: Mouse wheel
// - Zoom: Ctrl + Mouse wheel

Orbiting vs. Non-Orbiting

Non-Orbiting (Default)

Controller.Orbiting := False;
  • Controller rotates in place
  • Camera stays at fixed distance from controller
  • Good for first-person style navigation

Orbiting Mode

Controller.Orbiting := True;
  • Camera rotates around the controller position
  • Controller acts as the focus point
  • Perfect for object inspection and turntables

Customizing Movement

Intensity (Sensitivity)

// Faster rotation
Controller.IntensityRotate := 2.0;  // Default: 1.0

// Slower up/down movement
Controller.IntensityUpAndDown := 0.5;

// More sensitive zoom
Controller.IntensityZoom := 1.5;

// Faster shifting
Controller.ShiftIntensity := 2.0;

Damping (Smoothness)

Higher damping = slower impulse decay = smoother, more "floaty" movement:

// Very smooth rotation
Controller.DampingRotate := 0.95;  // Default: 0.85

// Quick stop for zoom
Controller.DampingZoom := 0.7;

// Smooth shifting
Controller.ShiftDamping := 0.9;

Movement Limits

Constrain camera movement to specific bounds:

// Limit rotation angle (in degrees)
Controller.LimitRotationMin := -180;
Controller.LimitRotationMax := 180;

// Limit vertical movement
Controller.LimitUpAndDownMin := -10;
Controller.LimitUpAndDownMax := 20;

// Limit zoom distance
Controller.LimitZoomMin := 5;
Controller.LimitZoomMax := 50;

Programmatic Control

Adding Impulses

// Rotate left (negative) or right (positive)
Controller.AddXImpulse(-0.5);

// Move up (positive) or down (negative)
Controller.AddYImpulse(0.3);

// Combined rotation and vertical movement
Controller.AddImpulse(PointF(0.5, -0.2));

Zooming

// Zoom in
Controller.Zoom(1.0);

// Zoom out
Controller.Zoom(-1.0);

// Stronger zoom
Controller.Zoom(2.0);

Shifting

// Shift on all axes
Controller.Shift(Point3D(1, 0, 0.5));

Direct Positioning

// Set exact position and angle
Controller.SetPositionAndAngle(
  Point3D(0, 5, 0),      // Position
  Point3D(0, 45, 0)      // Rotation angles
);

Custom Input Controls

Define your own mouse/keyboard combinations:

// Use middle mouse button for rotation
Controller.Rotation := [cssMiddle];

// Use Ctrl + Left button for shifting
Controller.Shifting := [cssCtrl, cssLeft];

// Use Shift + Right mouse button to move the camera up or down
Controller.ShiftUp := [cssRight + cssShift];

// Use Alt + Mouse wheel for zoom
Controller.Zooming := [cssAlt, cssMouseWheel];

Enabling/Disabling Controls

Selectively enable or disable control types:

// Enable all controls
Controller.Types := [scctRotateX, scctRotateY, scctMoveY, scctZoom,
                     scctShiftX, scctShiftY, scctShiftZ];

// Only allow rotation and zoom
Controller.Types := [scctRotateY, scctZoom];

// Lock camera (disable all controls)
Controller.Types := [];

Events

React to camera movements:

procedure TForm1.CameraControllerBeforeModify(ASender: TObject;
  AType: TGorillaSmoothCameraControlType; var AValue: Single);
begin
  // Modify the value before it's applied
  case AType of
    scctZoom:
      begin
        // Limit zoom speed
        if Abs(AValue) > 5 then
          AValue := Sign(AValue) * 5;
      end;
  end;
end;

procedure TForm1.CameraControllerAfterModify(ASender: TObject;
  AType: TGorillaSmoothCameraControlType; var AValue: Single);
begin
  // React to camera changes
  case AType of
    scctZoom:
      StatusBar1.Text := Format('Zoom: %.2f', [AValue]);
  end;
end;

// Assign events
Controller.OnBeforeModify := CameraControllerBeforeModify;
Controller.OnAfterModify := CameraControllerAfterModify;

Advanced Techniques

Object Inspector Pattern

Perfect for viewing 3D models:

procedure SetupObjectInspector(AController: TGorillaSmoothCameraController);
begin
  // Use orbiting mode
  AController.Orbiting := True;
  AController.NavigationProfile := cnpOrbit;

  // Center on object
  AController.Position.Point := Point3D(0, 0, 0);

  // Set comfortable distance
  AController.Camera.Position.Z := -20;

  // Limit zoom range
  AController.LimitZoomMin := 10;
  AController.LimitZoomMax := 100;

  // Smooth movement
  AController.DampingRotate := 0.92;
  AController.DampingZoom := 0.88;
end;

First-Person Camera

Navigation style for games and walkthroughs:

procedure SetupFirstPersonCamera(AController: TGorillaSmoothCameraController);
begin
  // No orbiting
  AController.Orbiting := False;
  AController.NavigationProfile := cnpDefault;

  // Quick response
  AController.DampingRotate := 0.75;
  AController.DampingZoom := 0.7;

  // Higher sensitivity
  AController.IntensityRotate := 1.5;
  AController.IntensityZoom := 2.0;

  // Limit vertical look angle
  AController.LimitUpAndDownMin := -30;
  AController.LimitUpAndDownMax := 30;
end;

Animated Camera Movement

Smoothly move camera to a target position:

procedure AnimateCameraToPosition(AController: TGorillaSmoothCameraController;
  ATarget: TPoint3D);
var
  Delta: TPoint3D;
begin
  Delta := ATarget - AController.Position.Point;

  // Add impulses to move toward target
  AController.Shift(Delta * 0.1);  // Adjust multiplier for speed
end;

// Call repeatedly in a timer or render loop until close enough

Camera Shake Effect

procedure AddCameraShake(AController: TGorillaSmoothCameraController;
  AIntensity: Single);
begin
  AController.AddImpulse(PointF(
    Random * AIntensity * 2 - AIntensity,  // Random X
    Random * AIntensity * 2 - AIntensity   // Random Y
  ));
end;

Best Practices

  1. Always Link Viewport: Set the Viewport property for automatic mouse event handling

  2. Choose Appropriate Profile: Use preset profiles when possible instead of custom configurations

  3. Set Reasonable Limits: Always define min/max limits to prevent users from getting lost

  4. Adjust Damping for Feel: Lower damping (0.7-0.8) for responsive controls, higher damping (0.9-0.95) for smooth, cinematic movement

  5. Test on Target Platform: Camera feel can differ between desktop (mouse) and mobile (touch) platforms

  6. Consider Scene Scale: Adjust intensity and zoom limits based on your scene size

  7. Provide Visual Feedback: Show controller position with ShowController := True during development

Troubleshooting

Camera Not Responding

// Check all required properties are set
if not Assigned(Controller.Camera) then
  ShowMessage('Camera not linked!');

if not Assigned(Controller.Viewport) then
  ShowMessage('Viewport not linked!');

if not Controller.Enabled then
  ShowMessage('Controller is disabled!');

Movement Too Fast/Slow

// Adjust intensity
Controller.IntensityRotate := 0.5;  // Slower
Controller.IntensityZoom := 2.0;    // Faster

Camera Drifts Continuously

// Increase damping to stop movement faster
Controller.DampingRotate := 0.95;
Controller.DampingZoom := 0.92;

// Or reset impulses manually
Controller.Impulse := Point3D(0, 0, 0);
Controller.ShiftImpulse := Point3D(0, 0, 0);

See Also