Qdoc documentation for new scene and input classes.

Change-Id: I5d9680fcf2e49655c1b9bcdf961bbda02bf31968
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@digia.com>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

1 files changed, 150 insertions, 74 deletions

diff --git a/src/datavisualization/engine/q3dscene.cpp b/src/datavisualization/engine/q3dscene.cpp
index 29eb54f4..2ad15a03 100644
--- a/src/datavisualization/engine/q3dscene.cpp
+++ b/src/datavisualization/engine/q3dscene.cpp
@@ -26,19 +26,48 @@
 #include "q3dlight_p.h"
 
 QT_DATAVISUALIZATION_BEGIN_NAMESPACE
-
+/*!
+ * \class Q3DScene
+ * \inmodule QtDataVisualization
+ * \brief Q3DScene class provides description of the 3D scene being visualized.
+ * \since 1.0.0
+ *
+ * The 3D scene contains a single active camera and a single active light source.
+ * Visualized data is assumed to be at a fixed location.
+ *
+ * The 3D scene also keeps track of the viewport in which visualization rendering is done,
+ * the primary subviewport inside the viewport where the main 3D data visualization view resides
+ * and the secondary subviewport where the 2D sliced view of the data resides.
+ *
+ * Also the scene has flag for tracking if the secondary 2D slicing view is currently active or not.
+ * \note Not all visualizations support the secondary 2D slicing view.
+ */
+
+/*!
+ * Constructs a basic scene with one light and one camera in it. An
+ * optional \a parent parameter can be given and is then passed to QObject constructor.
+ */
 Q3DScene::Q3DScene(QObject *parent) :
     QObject(parent),
     d_ptr(new Q3DScenePrivate(this))
 {
-    setCamera(new Q3DCamera(0));
-    setLight(new Q3DLight(0));
+    setActiveCamera(new Q3DCamera(0));
+    setActiveLight(new Q3DLight(0));
 }
 
+/*!
+ * Destroys the 3D scene and all the objects contained within it.
+ */
 Q3DScene::~Q3DScene()
 {
 }
 
+/*!
+ * \property Q3DScene::viewport
+ *
+ * This property contains the current viewport rectangle where all 3D rendering
+ * is targeted.
+ */
 QRect Q3DScene::viewport() const
 {
     return d_ptr->m_viewport;
@@ -55,6 +84,9 @@ void Q3DScene::setViewport(const QRect &viewport)
     }
 }
 
+/*!
+ * Sets the \a width and \a height of the viewport only, without changing its location.
+ */
 void Q3DScene::setViewportSize(int width, int height)
 {
     if (d_ptr->m_viewport.width() != width || d_ptr->m_viewport.height() != height) {
@@ -64,96 +96,162 @@ void Q3DScene::setViewportSize(int width, int height)
     }
 }
 
-QRect Q3DScene::mainViewport() const
+/*!
+ * \property Q3DScene::primarySubViewport
+ *
+ * This property contains the current main viewport rectangle inside the viewport where the
+ * primary view of the data visualization is targeted to.
+ */
+QRect Q3DScene::primarySubViewport() const
 {
-    return d_ptr->m_mainViewport;
+    return d_ptr->m_primarySubViewport;
 }
 
-void Q3DScene::setMainViewport(const QRect &mainViewPort)
+void Q3DScene::setPrimarySubViewport(const QRect &primarySubViewport)
 {
-    if (d_ptr->m_mainViewport != mainViewPort) {
-        d_ptr->m_mainViewport = mainViewPort;
-        d_ptr->m_changeTracker.mainViewportChanged = true;
+    if (d_ptr->m_primarySubViewport != primarySubViewport) {
+        d_ptr->m_primarySubViewport = primarySubViewport;
+        d_ptr->m_changeTracker.primarySubViewportChanged = true;
     }
 }
 
-bool Q3DScene::isInputInsideMainView(const QPoint &point)
+/*!
+ * Returns whether the given \a point resides inside the primary subview or not.
+ * The method takes care of correctly mapping between OpenGL coordinates used in the
+ * viewport definitions and the Qt event coordinate system used in the input system.
+ * \return true if the point is inside the primary subview.
+ */
+bool Q3DScene::isPointInPrimarySubView(const QPoint &point)
 {
+    // TODO: Needs fixing. Doesn't respect whether slice or main view is on top or if slicing is even activated currently.
     int x = point.x();
     int y = point.y();
-    int areaMinX = d_ptr->m_mainViewport.x();
-    int areaMaxX = d_ptr->m_mainViewport.x() + d_ptr->m_mainViewport.width();
-    int areaMaxY = d_ptr->m_viewport.height() - d_ptr->m_mainViewport.y();
-    int areaMinY = d_ptr->m_viewport.height() - (d_ptr->m_mainViewport.y() + d_ptr->m_mainViewport.height());
+    int areaMinX = d_ptr->m_primarySubViewport.x();
+    int areaMaxX = d_ptr->m_primarySubViewport.x() + d_ptr->m_primarySubViewport.width();
+    int areaMaxY = d_ptr->m_viewport.height() - d_ptr->m_primarySubViewport.y();
+    int areaMinY = d_ptr->m_viewport.height() - (d_ptr->m_primarySubViewport.y() + d_ptr->m_primarySubViewport.height());
 
     return ( x > areaMinX && x < areaMaxX && y > areaMinY && y < areaMaxY );
 }
 
-bool Q3DScene::isInputInsideSliceView(const QPoint &point)
+/*!
+ * Returns whether the given \a point resides inside the secondary subview or not.
+ * The method takes care of correctly mapping between OpenGL coordinates used in the
+ * viewport definitions and the Qt event coordinate system used in the input system.
+ * \return true if the point is inside the secondary subview.
+ */
+bool Q3DScene::isPointInSecondarySubView(const QPoint &point)
 {
+    // TODO: Needs fixing. Doesn't respect whether slice or main view is on top or if slicing is even activated currently.
     int x = point.x();
     int y = point.y();
-    int areaMinX = d_ptr->m_sliceViewport.x();
-    int areaMaxX = d_ptr->m_sliceViewport.x() + d_ptr->m_sliceViewport.width();
-    int areaMaxY = d_ptr->m_viewport.height() - d_ptr->m_sliceViewport.y();
-    int areaMinY = d_ptr->m_viewport.height() - (d_ptr->m_sliceViewport.y() + d_ptr->m_sliceViewport.height());
+    int areaMinX = d_ptr->m_secondarySubViewport.x();
+    int areaMaxX = d_ptr->m_secondarySubViewport.x() + d_ptr->m_secondarySubViewport.width();
+    int areaMaxY = d_ptr->m_viewport.height() - d_ptr->m_secondarySubViewport.y();
+    int areaMinY = d_ptr->m_viewport.height() - (d_ptr->m_secondarySubViewport.y() + d_ptr->m_secondarySubViewport.height());
 
     return ( x > areaMinX && x < areaMaxX && y > areaMinY && y < areaMaxY );
 }
 
-QRect Q3DScene::sliceViewport() const
+/*!
+ * \property Q3DScene::secondarySubViewport
+ *
+ * This property contains the secondary viewport rectangle inside the viewport. The secondary
+ * viewport is used for drawing the 2D slice view in some visualizations.
+ */
+QRect Q3DScene::secondarySubViewport() const
 {
-    return d_ptr->m_sliceViewport;
+    return d_ptr->m_secondarySubViewport;
 }
 
-void Q3DScene::setSliceViewport(const QRect &sliceViewPort)
+void Q3DScene::setSecondarySubViewport(const QRect &secondarySubViewport)
 {
-    if (d_ptr->m_sliceViewport != sliceViewPort) {
-        d_ptr->m_sliceViewport = sliceViewPort;
-        d_ptr->m_changeTracker.sliceViewportChanged = true;
+    if (d_ptr->m_secondarySubViewport != secondarySubViewport) {
+        d_ptr->m_secondarySubViewport = secondarySubViewport;
+        d_ptr->m_changeTracker.secondarySubViewportChanged = true;
     }
 }
 
-// TODO: Refactor the current way of building the scene...
-//       The scene should have clear ownership of camera, light and other future building blocks of the scene.
+/*!
+ * \property Q3DScene::slicingActive
+ *
+ * This property contains whether 2D slicing view is currently active or not.
+ * \note Not all visualizations support the 2D slicing view.
+ */
+bool Q3DScene::isSlicingActive() const
+{
+    return d_ptr->m_isSlicingActive;
+}
 
-Q3DCamera *Q3DScene::camera() const
+void Q3DScene::setSlicingActive(bool isSlicing)
+{
+    if (d_ptr->m_isSlicingActive != isSlicing) {
+        d_ptr->m_isSlicingActive = isSlicing;
+        d_ptr->m_changeTracker.slicingActivatedChanged = true;
+    }
+}
+
+/*!
+ * \property Q3DScene::activeCamera
+ *
+ * This property contains the currently active camera in the 3D scene.
+ * When a new Q3DCamera objects is set in the property it gets automatically added as child of the scene.
+ */
+Q3DCamera *Q3DScene::activeCamera() const
 {
     return d_ptr->m_camera;
 }
 
-void Q3DScene::setCamera(Q3DCamera *camera)
+void Q3DScene::setActiveCamera(Q3DCamera *camera)
 {
-    if (camera != d_ptr->m_camera) {
-        // TODO Do we need to be able to swap cameras? May need similar ownership mechanism like axes
-        delete d_ptr->m_camera;
+    // Add new camera as child of the scene
+    if (!children().contains(camera))
+        camera->setParent(this);
 
+    if (camera != d_ptr->m_camera) {
         d_ptr->m_camera = camera;
-        d_ptr->m_camera->setParentScene(this);
-
         d_ptr->m_changeTracker.cameraChanged = true;
-
     }
 }
 
-Q3DLight *Q3DScene::light() const
+/*!
+ * \property Q3DScene::activeLight
+ *
+ * This property contains the currently active light in the 3D scene.
+ * When a new Q3DLight objects is set in the property it gets automatically added as child of the scene.
+ */
+Q3DLight *Q3DScene::activeLight() const
 {
     return d_ptr->m_light;
 }
 
-void Q3DScene::setLight(Q3DLight *light)
+void Q3DScene::setActiveLight(Q3DLight *light)
 {
-    if (light != d_ptr->m_light) {
-        // TODO Do we need to be able to swap lights? May need similar ownership mechanism like axes
-        delete d_ptr->m_light;
+    // Add new light as child of the scene
+    if (!children().contains(light))
+        light->setParent(this);
 
+    if (light != d_ptr->m_light) {
         d_ptr->m_light = light;
-        d_ptr->m_light->setParentScene(this);
-
         d_ptr->m_changeTracker.lightChanged = true;
     }
 }
 
+/*!
+ * Calculates and sets the light position relative to the currently active camera using the given parameters.
+ * \a relativePosition defines the relative 3D offset to the current camera position.
+ * Optional \a fixedRotation fixes the light rotation around the data visualization area to the given value in degrees.
+ * Optional \a distanceModifier modifies the distance of the light from the data visualization.
+ */
+void Q3DScene::setLightPositionRelativeToCamera(const QVector3D &relativePosition,
+                                                qreal fixedRotation, qreal distanceModifier)
+{
+    d_ptr->m_light->setPosition(
+                d_ptr->m_camera->calculatePositionRelativeToCamera(relativePosition,
+                                                                   fixedRotation,
+                                                                   distanceModifier));
+}
+
 bool Q3DScene::isUnderSideCameraEnabled() const
 {
     return d_ptr->m_isUnderSideCameraEnabled;
@@ -167,35 +265,13 @@ void Q3DScene::setUnderSideCameraEnabled(bool isEnabled)
     }
 }
 
-bool Q3DScene::isSlicingActivated() const
-{
-    return d_ptr->m_isSlicingActivated;
-}
-
-void Q3DScene::setSlicingActivated(bool isSlicing)
-{
-    if (d_ptr->m_isSlicingActivated != isSlicing) {
-        d_ptr->m_isSlicingActivated = isSlicing;
-        d_ptr->m_changeTracker.slicingActivatedChanged = true;
-    }
-}
-
-void Q3DScene::setLightPositionRelativeToCamera(const QVector3D &relativePosition,
-                                                qreal fixedRotation, qreal distanceModifier)
-{
-    d_ptr->m_light->setPosition(
-                d_ptr->m_camera->calculatePositionRelativeToCamera(relativePosition,
-                                                                   fixedRotation,
-                                                                   distanceModifier));
-}
-
 
 Q3DScenePrivate::Q3DScenePrivate(Q3DScene *q) :
     q_ptr(q),
     m_camera(),
     m_light(),
     m_isUnderSideCameraEnabled(false),
-    m_isSlicingActivated(false)
+    m_isSlicingActive(false)
 {
 }
 
@@ -214,15 +290,15 @@ void Q3DScenePrivate::sync(Q3DScenePrivate &other)
         m_changeTracker.viewportChanged = false;
         other.m_changeTracker.viewportChanged = false;
     }
-    if (m_changeTracker.mainViewportChanged) {
-        other.q_ptr->setMainViewport(q_ptr->mainViewport());
-        m_changeTracker.mainViewportChanged = false;
-        other.m_changeTracker.mainViewportChanged = false;
+    if (m_changeTracker.primarySubViewportChanged) {
+        other.q_ptr->setPrimarySubViewport(q_ptr->primarySubViewport());
+        m_changeTracker.primarySubViewportChanged = false;
+        other.m_changeTracker.primarySubViewportChanged = false;
     }
-    if (m_changeTracker.sliceViewportChanged) {
-        other.q_ptr->setSliceViewport(q_ptr->sliceViewport());
-        m_changeTracker.sliceViewportChanged = false;
-        other.m_changeTracker.sliceViewportChanged = false;
+    if (m_changeTracker.secondarySubViewportChanged) {
+        other.q_ptr->setSecondarySubViewport(q_ptr->secondarySubViewport());
+        m_changeTracker.secondarySubViewportChanged = false;
+        other.m_changeTracker.secondarySubViewportChanged = false;
     }
     if (m_changeTracker.cameraChanged) {
         m_camera->setDirty(true);
@@ -244,7 +320,7 @@ void Q3DScenePrivate::sync(Q3DScenePrivate &other)
         other.m_changeTracker.underSideCameraEnabledChanged = false;
     }
     if (m_changeTracker.slicingActivatedChanged) {
-        other.q_ptr->setSlicingActivated(q_ptr->isSlicingActivated());
+        other.q_ptr->setSlicingActive(q_ptr->isSlicingActive());
         m_changeTracker.slicingActivatedChanged = false;
         other.m_changeTracker.slicingActivatedChanged = false;
     }