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>

5 files changed, 295 insertions, 16 deletions

diff --git a/src/doc/src/qmlextracontrollers.qdoc b/src/doc/src/qmlextracontrollers.qdoc
new file mode 100644
index 000000000..737d0f823
--- /dev/null
+++ b/src/doc/src/qmlextracontrollers.qdoc
@@ -0,0 +1,170 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype FirstPersonCameraController
+    \inqmlmodule Qt3D.Extras
+    \brief The FirstPersonCameraController allows controlling the scene camera
+    from the first person perspective.
+    \since 5.7
+    \inherits Qt3D.Core::Entity
+
+    The FirstPersonCameraController allows controlling the scene camera from the first person
+    perspective.
+
+    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
+*/
+/*!
+    \qmlproperty Camera FirstPersonCameraController::camera
+
+    Holds the currently controlled camera.
+*/
+/*!
+    \qmlproperty real FirstPersonCameraController::linearSpeed
+
+    Holds the current linear speed of the camera controller. Linear speed determines the
+    movement speed of the camera.
+*/
+/*!
+    \qmlproperty real FirstPersonCameraController::lookSpeed
+
+    Holds the current look speed of the camera controller. The look speed determines the turn rate
+    of the camera pan and tilt.
+*/
+/*!
+    \qmlproperty real FirstPersonCameraController::acceleration
+
+    Holds the current acceleration.
+    Specifies the rate at which the camera linear speed increases when a key is held.
+    If the acceleration is negative, the linear speed stays constant.
+    Defaults to -1.0.
+*/
+/*!
+    \qmlproperty real FirstPersonCameraController::deceleration
+
+    Specifies the rate at which the camera linear speed decreases when a key is released.
+    If the deceleration is negative, the linear speed stays constant.
+    Defaults to -1.0.
+*/
+
+/*!
+    \qmltype OrbitCameraController
+    \inqmlmodule Qt3D.Extras
+    \brief The OrbitCameraController class allows controlling the scene camera along orbital path.
+    \since 5.7
+    \inherits Qt3D.Core::Entity
+
+    The OrbitCameraController class allows controlling the scene camera along orbital path.
+
+    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
+*/
+/*!
+    \qmlproperty Camera OrbitCameraController::camera
+
+    Holds the currently controlled camera.
+*/
+/*!
+    \qmlproperty real OrbitCameraController::linearSpeed
+
+    Holds the current linear speed of the camera controller. Linear speed determines the
+    movement speed of the camera.
+*/
+/*!
+    \qmlproperty real OrbitCameraController::lookSpeed
+
+    Holds the current look speed of the camera controller. The look speed determines the turn rate
+    of the camera pan and tilt.
+*/
+/*!
+    \qmlproperty real OrbitCameraController::zoomLimit
+
+    Holds the current zoom-in limit. The zoom-in limit determines how close to the view center
+    the camera can be zoomed.
+*/
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;
diff --git a/src/quick3d/imports/extras/defaults/qml/OrbitCameraController.qml b/src/quick3d/imports/extras/defaults/qml/OrbitCameraController.qml
index 328b7b98e..1f5fa5a7a 100644
--- a/src/quick3d/imports/extras/defaults/qml/OrbitCameraController.qml
+++ b/src/quick3d/imports/extras/defaults/qml/OrbitCameraController.qml
@@ -162,13 +162,13 @@ Entity {
                     id: keyboardZAxis
                     ButtonAxisInput {
                         sourceDevice: keyboardSourceDevice
-                        buttons: [Qt.Key_Up]
-                        scale: d.shiftPressed ? 1.0 : 0.0
+                        buttons: [Qt.Key_PageUp]
+                        scale: 1.0
                     }
                     ButtonAxisInput {
                         sourceDevice: keyboardSourceDevice
-                        buttons: [Qt.Key_Down]
-                        scale: d.shiftPressed ? -1.0 : 0.0
+                        buttons: [Qt.Key_PageDown]
+                        scale: -1.0
                     }
                 },
                 Axis {
@@ -176,12 +176,12 @@ Entity {
                     ButtonAxisInput {
                         sourceDevice: keyboardSourceDevice
                         buttons: [Qt.Key_Up]
-                        scale: d.shiftPressed ? 0.0 : 1.0
+                        scale: 1.0
                     }
                     ButtonAxisInput {
                         sourceDevice: keyboardSourceDevice
                         buttons: [Qt.Key_Down]
-                        scale: d.shiftPressed ? 0.0 : -1.0
+                        scale: -1.0
                     }
                 }
             ] // axes
@@ -205,8 +205,8 @@ Entity {
                     } else {
                         // Translate
                         root.camera.translate(Qt.vector3d(d.translationX, d.translationY, 0).times(dt));
-                        return
                     }
+                    return
                 } else if (d.rightMouseButtonPressed) {
                     // Orbit
                     root.camera.panAboutViewCenter(d.orbitX * dt, d.firstPersonUp);
@@ -220,14 +220,14 @@ Entity {
                 } else if (d.shiftPressed) {
                     if (zoomDistance(root.camera.position, root.camera.viewCenter) > root.zoomLimit * root.zoomLimit) {
                         // Dolly up to limit
-                        root.camera.translate(Qt.vector3d(0, 0, d.translationZ).times(dt), Camera.DontTranslateViewCenter);
+                        root.camera.translate(Qt.vector3d(0, 0, d.translationY).times(dt), Camera.DontTranslateViewCenter);
                     } else {
                         // Too close, Dolly backwards
                         root.camera.translate(Qt.vector3d(0, 0, -1).times(dt), Camera.DontTranslateViewCenter);
                     }
                 } else {
                     // Translate
-                    root.camera.translate(Qt.vector3d(d.translationX, d.translationY, 0).times(dt));
+                    root.camera.translate(Qt.vector3d(d.translationX, d.translationY, d.translationZ).times(dt));
                 }
             }
         }