3 files changed, 116 insertions, 7 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);
diff --git a/src/extras/defaults/qorbitcameracontroller.cpp b/src/extras/defaults/qorbitcameracontroller.cpp
index deeec7f0d..d8f468ed0 100644
--- a/src/extras/defaults/qorbitcameracontroller.cpp
+++ b/src/extras/defaults/qorbitcameracontroller.cpp
@@ -54,9 +54,46 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DExtras {
 
 /*!
- * \class QOrbitCameraController::QOrbitCameraController
- * \internal
- */
+    \class Qt3DExtras::QOrbitCameraController
+    \brief The QOrbitCameraController class allows controlling the scene camera along orbital path.
+    \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 moves the camera
+        left and right and movement along y-axis moves it up and down.
+    \row
+        \li Right mouse button
+        \li While the right mouse button is pressed, mouse movement along x-axis pans the camera
+        around the camera view center and movement along y-axis tilts it around the camera
+        view center.
+    \row
+        \li Both left and right mouse button
+        \li While both the left and the right mouse button are pressed, mouse movement along y-axis
+        zooms the camera in and out without changing the view center.
+    \row
+        \li Arrow keys
+        \li Move the camera vertically and horizontally relative to camera viewport.
+    \row
+        \li Page up and page down keys
+        \li Move the camera forwards and backwards.
+    \row
+        \li Shift key
+        \li Changes the behavior of the up and down arrow keys to zoom the camera in and out
+        without changing the view center. The other movement keys are disabled.
+    \row
+        \li Alt key
+        \li Changes the behovior of the arrow keys to pan and tilt the camera around the view
+        center. Disables the page up and page down keys.
+    \endtable
+*/
 
 QOrbitCameraControllerPrivate::QOrbitCameraControllerPrivate()
     : Qt3DCore::QEntityPrivate()
@@ -214,8 +251,8 @@ void QOrbitCameraControllerPrivate::_q_onTriggered(float dt)
                 m_camera->translate(QVector3D(clampInputs(m_rxAxis->value(), m_txAxis->value()) * m_linearSpeed,
                                               clampInputs(m_ryAxis->value(), m_tyAxis->value()) * m_linearSpeed,
                                               0) * dt);
-                return;
             }
+            return;
         }
         else if (m_rightMouseButtonAction->isActive()) {
             // Orbit
@@ -254,24 +291,47 @@ QOrbitCameraController::~QOrbitCameraController()
 {
 }
 
+/*!
+    \property QOrbitCameraController::camera
+
+    Holds the currently controlled camera.
+*/
 Qt3DRender::QCamera *QOrbitCameraController::camera() const
 {
     Q_D(const QOrbitCameraController);
     return d->m_camera;
 }
 
+/*!
+    \property QOrbitCameraController::linearSpeed
+
+    Holds the current linear speed of the camera controller. Linear speed determines the
+    movement speed of the camera.
+*/
 float QOrbitCameraController::linearSpeed() const
 {
     Q_D(const QOrbitCameraController);
     return d->m_linearSpeed;
 }
 
+/*!
+    \property QOrbitCameraController::lookSpeed
+
+    Holds the current look speed of the camera controller. The look speed determines the turn rate
+    of the camera pan and tilt.
+*/
 float QOrbitCameraController::lookSpeed() const
 {
     Q_D(const QOrbitCameraController);
     return d->m_lookSpeed;
 }
 
+/*!
+    \property QOrbitCameraController::zoomInLimit
+
+    Holds the current zoom-in limit. The zoom-in limit determines how close to the view center
+    the camera can be zoomed.
+*/
 float QOrbitCameraController::zoomInLimit() const
 {
     Q_D(const QOrbitCameraController);
diff --git a/src/extras/defaults/qorbitcameracontroller.h b/src/extras/defaults/qorbitcameracontroller.h
index fb4d0aa7a..e48e39142 100644
--- a/src/extras/defaults/qorbitcameracontroller.h
+++ b/src/extras/defaults/qorbitcameracontroller.h
@@ -62,7 +62,6 @@ public:
     explicit QOrbitCameraController(Qt3DCore::QNode *parent = nullptr);
     ~QOrbitCameraController();
 
-    float clampInputs(float input1, float input2);
     Qt3DRender::QCamera *camera() const;
     float linearSpeed() const;
     float lookSpeed() const;