Gorilla.Camera Unit Reference

Overview

The Gorilla.Camera unit provides camera components for controlling the view in Gorilla3D scenes. It includes the main camera component TGorillaCamera and the smooth camera controller TGorillaSmoothCameraController for interactive camera navigation.

Classes

TGorillaCamera

Extended camera component inheriting from FireMonkey's TCamera with additional functionality for Gorilla3D rendering.

Inheritance: TCamera → TGorillaCamera

Platforms: All Gorilla3D supported platforms

Public Properties

Property Type Access Description
Def TCameraDef Read Access to the camera definition object containing camera parameters.
UpdateNeeded Boolean Read Indicates whether the camera needs to be updated.
PerspectiveMatrix TMatrix3D Read Returns the current perspective projection matrix.

Published Properties

Property Type Description
FOV Single Get or set the field of view angle in degrees.

Public Methods

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

Standard lifecycle methods.

procedure AssignFrom(Src: TPersistent);

Copy camera settings from another persistent object.

procedure LoadFromDefinition(const ADef: TCameraDef); virtual;

Load camera settings from a camera definition object.

procedure Update(); virtual;

Update the camera state.


TGorillaSmoothCameraController

Interactive camera controller providing smooth, impulse-based camera navigation. This component is a TDummy that contains a camera and controls it through physics-like impulses.

Inheritance: TDummy → TGorillaSmoothCameraController

Platforms: All Gorilla3D supported platforms

Public Properties

Property Type Access Description
Impulse TPoint3D Read/Write Current impulse for rotation around Y-axis (X), moving up/down (Y), and zooming (Z).
ShiftImpulse TPoint3D Read/Write Current impulse for shifting on X, Y, and Z axes.

Published Properties

Control Types
Property Type Description
Types TGorillaSmoothCameraControlTypes Enable or disable control types: rotation, movement, zooming, and shifting.
Impulse Limits
Property Type Description
ImpulseLimitRotate Single Maximum input value for rotation impulse.
ImpulseLimitUpAndDown Single Maximum input value for up/down movement impulse.
ImpulseLimitZoom Single Maximum input value for zoom impulse.
Intensity Settings
Property Type Description
IntensityRotate Single Intensity (sensitivity) of camera rotation.
IntensityUpAndDown Single Intensity (sensitivity) of camera up/down movement.
IntensityZoom Single Intensity (sensitivity) of camera zoom.
Damping Settings
Property Type Description
DampingRotate Single Damping factor for rotation impulse. Higher = slower decay.
DampingUpAndDown Single Damping factor for up/down movement impulse.
DampingZoom Single Damping factor for zoom impulse.
Movement Limits
Property Type Description
LimitRotationMin Single Minimum rotation angle around Y-axis.
LimitRotationMax Single Maximum rotation angle around Y-axis.
LimitUpAndDownMin Single Minimum position on Y-axis for up/down movement.
LimitUpAndDownMax Single Maximum position on Y-axis for up/down movement.
LimitZoomMin Single Minimum zoom distance on Z-axis.
LimitZoomMax Single Maximum zoom distance on Z-axis.
Shift Settings
Property Type Description
ShiftImpulseLimit Single Maximum shift impulse value.
ShiftDamping Single Damping factor for shifting impulse.
ShiftIntensity Single Intensity (sensitivity) of shifting on X, Y, and Z axes.
References
Property Type Description
Camera TCamera Link to the camera component to control. Controller does nothing if no camera is linked.
Viewport TControl Link to viewport for automatic mouse event registration. If not linked, you must call control methods manually.
Behavior Settings
Property Type Description
ShowController Boolean Show/hide a cube rendered at the controller position (for debugging).
Interval Integer Internal update interval in milliseconds.
Enabled Boolean Enable or disable the controller.
Orbiting Boolean Enable orbiting navigation mode where camera rotates around the controller instead of the controller rotating.
NavigationProfile TGorillaCameraNavigationProfile Choose between preset navigation profiles (Default, Orbit, InvOrbit, Blender, Sketchfab).
Input Control Settings
Property Type Description
Shifting TCameraShiftState Input controls to allow shifting (default: right mouse button).
ShiftUp TCameraShiftState Input controls to allow shifting upwards (default: Shift + right mouse button).
Zooming TCameraShiftState Input controls to allow zooming (default: mouse wheel).
Rotation TCameraShiftState Input controls to allow rotation (default: left mouse button).
Events
Property Type Description
OnBeforeModify TOnCameraControllerEvent Callback event before a control type is modified.
OnAfterModify TOnCameraControllerEvent Callback event after a control type was modified.

Public Methods

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

Standard lifecycle methods.

procedure AddImpulse(AOfs: TPointF); virtual;

Add rotation impulse (AOfs.X) and up/down movement impulse (AOfs.Y).

procedure AddXImpulse(AAngle: Single); virtual;

Add rotation impulse around Y-axis.

procedure AddYImpulse(AAngle: Single); virtual;

Add up/down movement impulse.

procedure Zoom(AStrength: Single = 1); virtual;

Zoom in or out. Positive values zoom in, negative values zoom out.

procedure Shift(AOfs: TPoint3D); virtual;

Move the camera controller on X, Y, and Z axes.

procedure SetPositionAndAngle(const APos: TPoint3D; const AAngle: TPoint3D);

Set the controller to a specific position and angle.

Types

TGorillaSmoothCameraControlType

Enumeration defining types of camera controls.

Values:

  • scctRotateX - Rotation around X-axis
  • scctRotateY - Rotation around Y-axis
  • scctMoveY - Movement on Y-axis (up/down)
  • scctZoom - Zoom in/out
  • scctShiftX - Shift on X-axis
  • scctShiftY - Shift on Y-axis
  • scctShiftZ - Shift on Z-axis

TGorillaSmoothCameraControlTypes

Set of TGorillaSmoothCameraControlType values.

TGorillaCameraNavigationProfile

Enumeration of preset navigation profiles.

Values:

  • cnpDefault - No orbiting, rotation by LMB, shifting xz-axes by RMB, shifting xy-axes by Shift+RMB, zooming by mouse wheel
  • cnpOrbit - With orbiting, rotation by RMB, shifting xy-axes by LMB, shifting xz-axes by Shift+LMB, zooming by mouse wheel
  • cnpInvOrbit - With orbiting, rotation by LMB, shifting xy-axes by RMB, shifting xz-axes by Shift+RMB, zooming by mouse wheel
  • cnpBlender - Blender-like navigation: with orbiting, rotation by Ctrl+RMB, shifting xy-axes by Ctrl+LMB, shifting xz-axes by Shift+LMB, zooming by mouse wheel
  • cnpSketchfab - Sketchfab-like navigation: with orbiting, rotation by LMB, shifting xy-axes by RMB, shifting xz-axes by Shift+RMB, move-forward by mouse wheel, zoom by Ctrl+mouse wheel

TCameraShiftStateItem

Mouse and keyboard state items for input control.

Values:

  • cssShift - Shift key pressed
  • cssAlt - Alt key pressed
  • cssCtrl - Ctrl key pressed
  • cssLeft - Left mouse button
  • cssRight - Right mouse button
  • cssMiddle - Middle mouse button
  • cssDouble - Double-click
  • cssTouch - Touch input
  • cssPen - Pen input
  • cssCommand - Command key (macOS)
  • cssHorizontal - Horizontal scrolling
  • cssMouseWheel - Mouse wheel

TCameraShiftState

Set of TCameraShiftStateItem values.

TOnCameraControllerEvent

Event callback for camera controller modifications.

TOnCameraControllerEvent = procedure(
  ASender: TObject;
  AType: TGorillaSmoothCameraControlType;
  var AValue: Single
) of object;

Parameters:

  • ASender - The controller triggering the event
  • AType - Type of control being modified
  • AValue - Current value (can be modified in the event handler)

Constants

INITIAL_CAMERA_ZOFFSET = -1.0;

Default Z-offset for camera positioning.

Usage Notes

  1. Camera Reference: Always set the Camera property of TGorillaSmoothCameraController to link it to a camera component.

  2. Viewport Integration: Set the Viewport property for automatic mouse event handling. Without this, you must manually call AddImpulse(), Zoom(), and Shift().

  3. Impulse System: The controller uses a physics-like impulse system with damping. Impulses gradually decrease over time based on damping settings.

  4. Orbiting Mode: In orbiting mode, the camera rotates around the controller position rather than rotating in place. This is useful for object inspection.

  5. Navigation Profiles: Use preset profiles for familiar navigation schemes from other 3D applications (Blender, Sketchfab, etc.).

  6. Limits: Set min/max limits to constrain camera movement within specific bounds.

See Also