Fix camera controllers

Fixed a few bugs and inconsistencies between qml and c++ implementations
of the camera controllers. Also documented them.

Task-number: QTBUG-55697
Change-Id: Ie490b0ca46f60a2a34c04f91572505e908ce65ba
Reviewed-by: Antti Määttä <antti.maatta@qt.io>
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

1 files changed, 52 insertions, 2 deletions

diff --git a/src/extras/defaults/qfirstpersoncameracontroller.cpp b/src/extras/defaults/qfirstpersoncameracontroller.cpp
index 0e1af51b3..973566a3c 100644
--- a/src/extras/defaults/qfirstpersoncameracontroller.cpp
+++ b/src/extras/defaults/qfirstpersoncameracontroller.cpp
@@ -184,12 +184,45 @@ void QFirstPersonCameraControllerPrivate::_q_onTriggered(float dt)
                                       m_tyAxis->value() * m_linearSpeed,
                                       m_tzAxis->value() * m_linearSpeed) * dt);
         if (m_leftMouseButtonAction->isActive()) {
-            m_camera->pan(m_rxAxis->value() * m_lookSpeed * dt, m_firstPersonUp);
-            m_camera->tilt(m_ryAxis->value() * m_lookSpeed * dt);
+            float lookSpeed = m_lookSpeed;
+            if (m_fineMotionAction->isActive())
+                lookSpeed *= 0.2f;
+            m_camera->pan(m_rxAxis->value() * lookSpeed * dt, m_firstPersonUp);
+            m_camera->tilt(m_ryAxis->value() * lookSpeed * dt);
         }
     }
 }
 
+/*!
+    \class Qt3DExtras::QFirstPersonCameraController
+    \brief The QFirstPersonCameraController class allows controlling the scene camera
+    from the first person perspective.
+    \inmodule Qt3DExtras
+    \since 5.7
+    \inherits Qt3DCore::QEntity
+
+    The controls are:
+    \table
+    \header
+        \li Input
+        \li Action
+    \row
+        \li Left mouse button
+        \li While the left mouse button is pressed, mouse movement along x-axis pans the camera and
+        movement along y-axis tilts it.
+    \row
+        \li Shift key
+        \li Turns the fine motion control active while pressed. Makes mouse pan and tilt less
+        sensitive.
+    \row
+        \li Arrow keys
+        \li Move the camera horizontally relative to camera viewport.
+    \row
+        \li Page up and page down keys
+        \li Move the camera vertically relative to camera viewport.
+    \endtable
+*/
+
 QFirstPersonCameraController::QFirstPersonCameraController(Qt3DCore::QNode *parent)
     : Qt3DCore::QEntity(*new QFirstPersonCameraControllerPrivate, parent)
 {
@@ -201,18 +234,35 @@ QFirstPersonCameraController::~QFirstPersonCameraController()
 {
 }
 
+/*!
+    \property QFirstPersonCameraController::camera
+
+    Holds the currently controlled camera.
+*/
 Qt3DRender::QCamera *QFirstPersonCameraController::camera() const
 {
     Q_D(const QFirstPersonCameraController);
     return d->m_camera;
 }
 
+/*!
+    \property QFirstPersonCameraController::linearSpeed
+
+    Holds the current linear speed of the camera controller. Linear speed determines the
+    movement speed of the camera.
+*/
 float QFirstPersonCameraController::linearSpeed() const
 {
     Q_D(const QFirstPersonCameraController);
     return d->m_linearSpeed;
 }
 
+/*!
+    \property QFirstPersonCameraController::lookSpeed
+
+    Holds the current look speed of the camera controller. The look speed determines the turn rate
+    of the camera pan and tilt.
+*/
 float QFirstPersonCameraController::lookSpeed() const
 {
     Q_D(const QFirstPersonCameraController);