Update documentation related to picking

Change-Id: I67f37da8d4534938e252a0c96735e6efe58cb6e3
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

5 files changed, 147 insertions, 33 deletions

diff --git a/src/render/frontend/qpickingsettings.cpp b/src/render/frontend/qpickingsettings.cpp
index db6840d7f..1cda638cb 100644
--- a/src/render/frontend/qpickingsettings.cpp
+++ b/src/render/frontend/qpickingsettings.cpp
@@ -53,6 +53,11 @@ namespace Qt3DRender {
 
     The picking settings determine how the entity picking is handled. For more details about
     entity picking, see QObjectPicker component documentation.
+
+    Picking is triggered by mouse events. It will cast a ray through the scene and look for
+    geometry intersecting the ray.
+
+    \sa QObjectPicker, QPickEvent, QPickTriangleEvent
  */
 
 /*!
@@ -64,6 +69,11 @@ namespace Qt3DRender {
 
     The picking settings determine how the entity picking is handled. For more details about
     entity picking, see Qt3DRender::QObjectPicker component documentation.
+
+    Picking is triggered by mouse events. It will cast a ray through the scene and look for
+    geometry intersecting the ray.
+
+    \sa ObjectPicker
  */
 
 QPickingSettingsPrivate::QPickingSettingsPrivate()
@@ -104,9 +114,6 @@ QPickingSettings::PickResultMode QPickingSettings::pickResultMode() const
     return d->m_pickResultMode;
 }
 
-/*!
- * \return the back facing picking flag
- */
 QPickingSettings::FaceOrientationPickingMode QPickingSettings::faceOrientationPickingMode() const
 {
     Q_D(const QPickingSettings);
@@ -119,7 +126,7 @@ QPickingSettings::FaceOrientationPickingMode QPickingSettings::faceOrientationPi
  * Specifies the picking method.
  *
  * \value BoundingVolumePicking An entity is considered picked if the picking ray intersects
- * the bounding volume of the entity.
+ * the bounding volume of the entity (default).
  * \value TrianglePicking An entity is considered picked if the picking ray intersects with
  * any triangle of the entity's mesh component.
  */
@@ -140,6 +147,12 @@ QPickingSettings::FaceOrientationPickingMode QPickingSettings::faceOrientationPi
     \property QPickingSettings::pickMethod
 
     Holds the current pick method.
+
+    By default, for performance reasons, ray casting will use bounding volume picking.
+    This may however lead to unexpected results if a small object is englobed
+    in the bounding sphere of a large object behind it.
+
+    Triangle picking will produce exact results but is computationally more expensive.
 */
 void QPickingSettings::setPickMethod(QPickingSettings::PickMethod pickMethod)
 {
@@ -157,8 +170,10 @@ void QPickingSettings::setPickMethod(QPickingSettings::PickMethod pickMethod)
  * Specifies what is included into the picking results.
  *
  * \value NearestPick Only the nearest entity to picking ray origin intersected by the picking ray
- * is picked.
+ * is picked (default).
  * \value AllPicks All entities that intersect the picking ray are picked.
+ *
+ * \sa Qt3DRender::QPickEvent
  */
 
 /*!
@@ -177,6 +192,14 @@ void QPickingSettings::setPickMethod(QPickingSettings::PickMethod pickMethod)
     \property QPickingSettings::pickResultMode
 
     Holds the current pick results mode.
+
+    By default, pick results will only be produced for the entity closest to the camera.
+
+    When setting the pick method to AllPicks, events will be triggered for all the
+    entities with a QObjectPicker along the ray.
+
+    If a QObjectPicker is assigned to an entity with multiple children, an event will
+    be triggered for each child entity that intersects the ray.
 */
 void QPickingSettings::setPickResultMode(QPickingSettings::PickResultMode pickResultMode)
 {
@@ -189,8 +212,31 @@ void QPickingSettings::setPickResultMode(QPickingSettings::PickResultMode pickRe
 }
 
 /*!
- * \a faceOrientationPickingMode determines whether back facing faces are picked or not.
- */
+    \enum Qt3DRender::QPickingSettings::FaceOrientationPickingMode
+
+    Specifies how face orientation affects triangle picking
+
+    \value FrontFace Only front-facing triangles will be picked (default).
+    \value BackFace Only back-facing triangles will be picked.
+    \value FrontAndBackFace Both front- and back-facing triangles will be picked.
+*/
+
+/*!
+    \qmlproperty enumeration PickingSettings::faceOrientationPickingMode
+
+    Specifies how face orientation affects triangle picking
+
+    \list
+        \li PickingSettings.FrontFace Only front-facing triangles will be picked (default).
+        \li PickingSettings.BackFace Only back-facing triangles will be picked.
+        \li PickingSettings.FrontAndBackFace Both front- and back-facing triangles will be picked.
+    \endlist
+*/
+/*!
+    \property QPickingSettings::faceOrientationPickingMode
+
+    Specifies how face orientation affects triangle picking
+*/
 void QPickingSettings::setFaceOrientationPickingMode(QPickingSettings::FaceOrientationPickingMode faceOrientationPickingMode)
 {
     Q_D(QPickingSettings);
diff --git a/src/render/geometry/qgeometry.cpp b/src/render/geometry/qgeometry.cpp
index 95405d64d..3d281866d 100644
--- a/src/render/geometry/qgeometry.cpp
+++ b/src/render/geometry/qgeometry.cpp
@@ -94,7 +94,13 @@ QGeometryPrivate::~QGeometryPrivate()
 /*!
     \qmlproperty Attribute Geometry::boundingVolumePositionAttribute
 
-    Holds the attribute used to compute the bounding volume.
+    Holds the attribute used to compute the bounding volume. The bounding volume is used internally
+    for picking and view frustum culling.
+
+    If unspecified, the system will look for the attribute using the name returned by
+    QAttribute::defaultPositionAttributeName.
+
+    \sa Attribute
  */
 /*!
     \qmlproperty list<Attribute> Geometry::attributes
@@ -105,7 +111,13 @@ QGeometryPrivate::~QGeometryPrivate()
 /*!
     \property QGeometry::boundingVolumePositionAttribute
 
-    Holds the attribute used to compute the bounding volume.
+    Holds the attribute used to compute the bounding volume. The bounding volume is used internally
+    for picking and view frustum culling.
+
+    If unspecified, the system will look for the attribute using the name returned by
+    QAttribute::defaultPositionAttributeName.
+
+    \sa Qt3DRender::QAttribute
  */
 
 
diff --git a/src/render/picking/qobjectpicker.cpp b/src/render/picking/qobjectpicker.cpp
index 9fa8b774c..45f7ff135 100644
--- a/src/render/picking/qobjectpicker.cpp
+++ b/src/render/picking/qobjectpicker.cpp
@@ -56,14 +56,25 @@ namespace Qt3DRender {
     \brief The QObjectPicker class instantiates a component that can
     be used to interact with a QEntity by a process known as picking.
 
+    For every combination of viewport and camera, picking casts a ray through the scene to
+    find entities who's bounding volume intersects the ray. The bounding volume is computed using
+    the values in the attribute buffer specified by the boundingVolumePositionAttribute of the
+    geometry.
+
     The signals pressed(), released(), clicked(), moved(), entered(), and exited() are
     emitted when the bounding volume defined by the pickAttribute property intersects
     with a ray.
 
+    Most signals carry a QPickEvent instance. If QPickingSettings::pickMode() is set to
+    QPickingSettings::TrianglePicking, the actual type of the pick parameter will be
+    QPickTriangleEvent.
+
     Pick queries are performed on mouse press and mouse release.
     If drag is enabled, queries also happen on each mouse move while any button is pressed.
     If hover is enabled, queries happen on every mouse move even if no button is pressed.
-    \sa QPickingSettings
+
+    \sa Qt3DRender::QPickingSettings, Qt3DRender::QGeometry, Qt3DRender::QAttribute,
+        Qt3DRender::QPickEvent, Qt3DRender::QPickTriangleEvent
 
     \note Instances of this component shouldn't be shared, not respecting that
     condition will most likely result in undefined behavior.
@@ -77,28 +88,51 @@ namespace Qt3DRender {
  * \inqmlmodule Qt3D.Render
  * \brief The ObjectPicker class instantiates a component that can
     be used to interact with an Entity by a process known as picking.
+
+    For every combination of viewport and camera, picking casts a ray through the scene to
+    find entities who's bounding volume intersects the ray. The bounding volume is computed using
+    the values in the attribute buffer specified by the boundingVolumePositionAttribute of the
+    geometry.
+
+    The signals pressed(), released(), clicked(), moved(), entered(), and exited() are
+    emitted when the bounding volume defined by the pickAttribute property intersects
+    with a ray.
+
+    Most signals carry a PickEvent instance. If PickingSettings.pickMode is set to
+    PickingSettings.TrianglePicking, the actual type of the pick parameter will be
+    PickTriangleEvent.
+
+    Pick queries are performed on mouse press and mouse release.
+    If drag is enabled, queries also happen on each mouse move while any button is pressed.
+    If hover is enabled, queries happen on every mouse move even if no button is pressed.
+
+    \sa PickingSettings, Geometry, Attribute, PickEvent, PickTriangleEvent
+
+    \note Instances of this component shouldn't be shared, not respecting that
+    condition will most likely result in undefined behavior.
+
  */
 
 /*!
-    \qmlsignal Qt3D.Render::ObjectPicker::pressed()
+    \qmlsignal Qt3D.Render::ObjectPicker::pressed(PickEvent pick)
   This signal is emitted when the bounding volume defined by the pickAttribute property intersects
     with a ray on a mouse press.
 */
 
 /*!
-    \qmlsignal Qt3D.Render::ObjectPicker::released()
+    \qmlsignal Qt3D.Render::ObjectPicker::released(PickEvent pick)
   This signal is emitted when the bounding volume defined by the pickAttribute property intersects
     with a ray on a mouse release.
 */
 
 /*!
-    \qmlsignal Qt3D.Render::ObjectPicker::clicked()
+    \qmlsignal Qt3D.Render::ObjectPicker::clicked(PickEvent pick)
   This signal is emitted when the bounding volume defined by the pickAttribute property intersects
     with a ray on a mouse click.
 */
 
 /*!
-    \qmlsignal Qt3D.Render::ObjectPicker::moved()
+    \qmlsignal Qt3D.Render::ObjectPicker::moved(PickEvent pick)
   This signal is emitted when the bounding volume defined by the pickAttribute property intersects
     with a ray on a mouse move with a button pressed.
 */
diff --git a/src/render/picking/qpickevent.cpp b/src/render/picking/qpickevent.cpp
index c7abf639c..806d91dc0 100644
--- a/src/render/picking/qpickevent.cpp
+++ b/src/render/picking/qpickevent.cpp
@@ -50,6 +50,10 @@ namespace Qt3DRender {
     \inmodule Qt3DRender
 
     \brief The QPickEvent class holds information when an object is picked
+
+    This is received as a parameter in most of the QObjectPicker component signals when picking
+    succeeds.
+
     \sa QPickingSettings, QPickTriangleEvent, QObjectPicker
 
     \since 5.7
@@ -61,9 +65,10 @@ namespace Qt3DRender {
  * \inqmlmodule Qt3D.Render
  * \sa ObjectPicker PickingSettings
  * \brief PickEvent holds information when an object is picked.
+ * This is received as a parameter in most of the QObjectPicker component signals when picking
+ * succeeds.
  */
 
-
 /*!
   \fn Qt3DRender::QPickEvent::QPickEvent()
   Constructs a new QPickEvent.
@@ -147,11 +152,11 @@ void QPickEvent::setAccepted(bool accepted)
 
 /*!
     \qmlproperty bool Qt3D.Render::PickEvent::position
-    Specifies the position of the event
+    Specifies the mouse position with respect to the render area (window or quick item)
 */
 /*!
   \property Qt3DRender::QPickEvent::position
-    Specifies the position of the event
+    Specifies the mouse position with respect to the render area (window or quick item)
  */
 /*!
  * \brief QPickEvent::position
@@ -165,11 +170,11 @@ QPointF QPickEvent::position() const
 
 /*!
     \qmlproperty bool Qt3D.Render::PickEvent::distance
-    Specifies the distance of the event
+    Specifies the distance of the hit to the camera
 */
 /*!
   \property Qt3DRender::QPickEvent::distance
-    Specifies the distance of the event
+    Specifies the distance of the hit to the camera
  */
 /*!
  * \brief QPickEvent::distance
@@ -183,15 +188,15 @@ float QPickEvent::distance() const
 
 /*!
     \qmlproperty bool Qt3D.Render::PickEvent::worldIntersection
-    Specifies the world intersection of the event
+    Specifies the coordinates of the hit in world coordinate system
 */
 /*!
   \property Qt3DRender::QPickEvent::worldIntersection
-    Specifies the world intersection of the event
+    Specifies the coordinates of the hit in world coordinate system
  */
 /*!
  * \brief QPickEvent::worldIntersection
- * \return  world coordinate of the pick point
+ * \return  coordinates of the hit in world coordinate system
  */
 QVector3D QPickEvent::worldIntersection() const
 {
@@ -201,15 +206,15 @@ QVector3D QPickEvent::worldIntersection() const
 
 /*!
     \qmlproperty bool Qt3D.Render::PickEvent::localIntersection
-    Specifies the world local intersection of the event
+    Specifies the coordinates of the hit in the local coordinate system of the picked entity
 */
 /*!
   \property Qt3DRender::QPickEvent::localIntersection
-    Specifies the local intersection of the event
+    Specifies the coordinates of the hit in the local coordinate system of the picked entity
  */
 /*!
  * \brief QPickEvent::localIntersection
- * \return local coordinate of pick point
+ * \return coordinates of the hit in the local coordinate system of the picked entity
  */
 QVector3D QPickEvent::localIntersection() const
 {
diff --git a/src/render/picking/qpicktriangleevent.cpp b/src/render/picking/qpicktriangleevent.cpp
index a1da8b975..3077cc91a 100644
--- a/src/render/picking/qpicktriangleevent.cpp
+++ b/src/render/picking/qpicktriangleevent.cpp
@@ -69,7 +69,15 @@ public:
 
     \brief The QPickTriangleEvent class holds information when a triangle is picked
 
-    \sa QPickEvent
+    When QPickingSettings::pickMode() is set to QPickingSettings::TrianglePicking, the signals
+    on QObjectPicker will carry an instance of QPickTriangleEvent.
+
+    This contains the details of the triangle that was picked.
+
+    \note In the case of indexed rendering, the point indices are relative to the
+    array of coordinates, not the array of indices.
+
+    \sa QPickingSettings, QPickEvent, QObjectPicker, QAttribute
     \since 5.7
 */
 
@@ -78,7 +86,16 @@ public:
  * \instantiates Qt3DRender::QPickTriangleEvent
  * \inqmlmodule Qt3D.Render
  * \brief PickTriangleEvent holds information when a triangle is picked.
- * \sa ObjectPicker
+ *
+ * When QPickingSettings::pickMode() is set to QPickingSettings::TrianglePicking, the signals
+ * on QObjectPicker will carry an instance of QPickTriangleEvent.
+ *
+ * This contains the details of the triangle that was picked.
+ *
+ * \note In case of indexed rendering, the point indices are relative to the
+ * array of indices, not the array of coordinates.
+ *
+ * \sa PickingSettings, PickEvent, ObjectPicker, Attribute
  */
 
 
@@ -160,11 +177,11 @@ uint QPickTriangleEvent::triangleIndex() const
 
 /*!
     \qmlproperty uint Qt3D.Render::PickTriangleEvent::vertex1Index
-    Specifies the vertex 1 index of the event
+    Specifies the index of the first vertex in the triangle
 */
 /*!
   \property Qt3DRender::QPickTriangleEvent::vertex1Index
-    Specifies the vertex 1 index of the event
+    Specifies the index of the first vertex in the triangle
  */
 /*!
  * \brief QPickTriangleEvent::vertex1Index
@@ -178,11 +195,11 @@ uint QPickTriangleEvent::vertex1Index() const
 
 /*!
     \qmlproperty uint Qt3D.Render::PickTriangleEvent::vertex2Index
-    Specifies the vertex 2 index of the event
+    Specifies the index of the second vertex in the triangle
 */
 /*!
   \property Qt3DRender::QPickTriangleEvent::vertex2Index
-    Specifies the vertex 2 index of the event
+    Specifies the index of the second vertex in the triangle
  */
 /*!
  * \brief QPickTriangleEvent::vertex2Index
@@ -196,11 +213,11 @@ uint QPickTriangleEvent::vertex2Index() const
 
 /*!
     \qmlproperty uint Qt3D.Render::PickTriangleEvent::vertex3Index
-    Specifies the vertex 3 index of the event
+    Specifies the index of the third vertex in the triangle
 */
 /*!
   \property Qt3DRender::QPickTriangleEvent::vertex3Index
-    Specifies the vertex 3 index of the event
+    Specifies the index of the third vertex in the triangle
  */
 /*!
  * \brief QPickTriangleEvent::vertex3Index