Differences

This shows you the differences between two versions of the page.

--- 0.8.4:cameras [2022/07/20 12:32] – [TGorillaSmoothCameraController] admin
+++ 0.8.4:cameras [2022/07/22 12:55] (current) – [Creating a Smooth Controller at Runtime] admin
@@ Line 33: / Line 33: @@
 ===== Target =====
-A very useful property of Firemonkey's TCamera component is the //Target// property. You can link the camera to another 3D object to always look at. This will compute view direction always towards the linked 3D object.
+A very useful property of Firemonkey's TCamera component is the //Target// property. You can link the camera to another 3D object to always look at it. This will generate a view direction always towards the linked 3D object.
 You can use this property for easy camera navigation in 3D space. Combine a camera component with a non-visual TDummy instance to navigate.
@@ Line 125: / Line 125: @@
 end;
 </file>
-===== TGorillaSmoothCameraController =====
-Since version 0.8.4.2341 a TGorillaViewport component provides an embedded //TGorillaSmoothCameraController// component with automatic mouse feedback integration. This means: In case //UsingDesignCamera// is set to TRUE, the viewport will register OnMouseDown, OnMouseUp and OnMouseMove events and forward those events to the embedded TGorillaSmoothCameraController.
+===== Frustum Culling =====
+The viewing frustum is a geometric representation of the volume visible to the virtual camera. Naturally, objects outside this volume will not be visible in the final image, so they are discarded.
+Read more about here: [[viewport#frustumculling|Frustum Culling]]
+===== Smooth Camera Controller =====
+Since version 0.8.4.2341 a TGorillaViewport component provides an embedded //TGorillaSmoothCameraController// component with automatic mouse feedback integration. This means: In case //TGorillaViewport.UsingDesignCamera// is set to TRUE, the viewport will register OnMouseDown, OnMouseUp and OnMouseMove events and forward those events to the embedded TGorillaSmoothCameraController.
 This enables an easy-to-use mouse navigation for your 3D scene without any effort.
-The component provides many options to configure behaviour of the camera controller.
+The smooth camera controller supports the following control:
+  * Rotation around Y-axis
+  * Rotation around X-axis (moving up / down)
+  * Zooming in / out
+  * Shifting / Translating on X-, Y- and Z-axis
+It is called "Smooth" because it moves smoothly and will not stop abruptly if user stops interacting. This provides a good user experience.
+Nevertheless you're able to control this smoothness and the controller itself by a variety of properties:
 ^Property ^ Description^
@@ Line 159: / Line 174: @@
 |OnBeforeModify|A callback event before a specific type of control (rotate, up/down, zoom, ...) getting modified.|
 |OnAfterModify|A callback event after a specific type of control (rotate, up/down, zoom, ...) was modified.|
+To retrieve and modify the embedded camera and camera controller from a viewport you can use the following public functions of a TGorillaViewport instance.
+^Function^
+|function GetDesignCamera() : TCamera;|
+|function GetDesignCameraController() : TGorillaSmoothCameraController;|
+==== Creating a Smooth Controller at Runtime ====
+Besides the embedded camera controller in the viewport, you can of course create your own at runtime or designtime.
+If you link the controller to a viewport component, it will automatically setup the necessary mouse events for you.
+But you are also allowed to control it yourself, f.e. by Gamepad or Keyboard events. For manual controlling please leave the viewport property empty.
+In the following code snippet we modify rotation manually in user-specific mouse events.
+We're also blocking shifting, because we only want to rotate the camera.
+<file pascal>
+uses
+  Gorilla.Camera;
+[...]
+type
+  TForm1 = class(TForm)
+    GorillaViewport1: TGorillaViewport;
+    FCameraCtrl : TGorillaSmoothCameraController;
+    FMyCamera : TGorillaCamera;
+  private
+    FIsMoving : Boolean;
+    FLastPoint : TPointF;
+    procedure DoOnViewportMouseUp(ASender : TObject; AButton : TMouseButton;
+      AShift : TShiftState; X, Y : Single);
+    procedure DoOnViewportMouseDown(ASender : TObject; AButton : TMouseButton;
+      AShift : TShiftState; X, Y : Single);
+    procedure DoOnViewportMouseMove(ASender : TObject; AShiftState : TShiftState;
+      X, Y : Single);
+  end;
+  [...]
+procedure TForm1.FormCreate(Sender: TObject);
+begin
+  /// Deactivate design camera controller before registering user-specific events for mouse feedback
+  GorillaViewport1.UsingDesignCamera := FALSE;
+  /// Register user-specific mouse events to control our camera
+  GorillaViewport1.OnMouseUp   := DoOnViewportMouseUp;
+  GorillaViewport1.OnMouseDown := DoOnViewportMouseDown;
+  GorillaViewport1.OnMouseMove := DoOnViewportMouseMove;
+  /// Create a smooth camera controller
+  FCameraCtrl := TGorillaSmoothCameraController.Create(GorillaViewport1);
+  FCameraCtrl.Parent := GorillaViewport;
+  /// NOTICE: Enable only rotation. Disable zooming and shifting
+  FCameraCtrl.Types := [TGorillaSmoothCameraControlType.scctRotateY, TGorillaSmoothCameraControlType.scctMoveY];
+  /// Create our own camera for this controller
+  FMyCamera := TGorillaCamera.Create(FCameraCtrl);
+  FMyCamera.Parent := FCameraCtrl;
+  /// Link the camera to the controller
+  FCameraCtrl.Camera := FMyCamera;
+  /// Activate the camera for rendering
+  GorillaViewport1.Camera := FMyCamera;
+  [...]
+end;
+procedure TForm1.DoOnViewportMouseUp(ASender : TObject; AButton : TMouseButton;
+  AShift : TShiftState; X, Y : Single);
+begin
+  FIsMoving := false;
+end;
+procedure TForm1.DoOnViewportMouseDown(ASender : TObject; AButton : TMouseButton;
+  AShift : TShiftState; X, Y : Single);
+begin
+  FIsMoving  := true;
+  FLastPoint := PointF(X, Y);
+end;
+procedure TForm1.DoOnViewportMouseMove(ASender : TObject; AShiftState : TShiftState;
+  X, Y : Single);
+var LDiff : TPointF;
+begin
+  if FIsMoving then
+  begin
+    if (ssLeft in AShiftState) then
+    begin
+      LDiff := PointF(X, Y) - FLastPoint;
+      /// Rotate around y-axis + Move up and down
+      FCameraCtrl.AddImpulse(LDiff);
+    end;
+    /// finally store the last mouse position
+    FLastPoint := PointF(X, Y);
+  end;
+end;
+</file>
+The smooth camera controller provides a number of helpful functions to modify it from external.
+^Function^Description^
+|procedure AddImpulse(AOfs : TPointF);|Call this procedure to rotate around Y axis (AOfs.X) and move the camera up or down (AOfs.Y).|
+|procedure AddXImpulse(AAngle : Single);|Call this procedure to rotate around Y axis.|
+|procedure AddYImpulse(AAngle : Single); |Call this procedure to move camera up and down.|
+|procedure Zoom(AStrength : Single = 1);|Call this procedure if you want to zoom in or out. The strength parameter defines the intensity of zooming.|
+|procedure Shift(AOfs : TPoint3D);|Move the camera controller on X, Y and Z axis.|
+You can manipulate impulse values for rotation, zooming and shifting directly by the following properties.
+^Property^Description^
+|Impulse.X|Get or set the current impulse for rotation around Y-axis (X value).|
+|Impulse.Y|Get or set the current impulse for moving up and down (Y value)|
+|Impulse.Z|Get or set the current impulse for zooming in/out (Z value)|
+|ShiftImpulse.X|Get or set the current impulse for shifting on X axis.|
+|ShiftImpulse.Y|Get or set the current impulse for shifting on Y axis.|
+|ShiftImpulse.Z|Get or set the current impulse for shifting on Z axis.|
+Next step: [[lights|Lights]]