Merge remote-tracking branch 'origin/2.0'v2.0.0-beta2

Change-Id: I1d34fa789a3962e6efe595fdd028db953749bd53

7 files changed, 612 insertions, 130 deletions

diff --git a/src/runtime/api/q3dsdatainput.cpp b/src/runtime/api/q3dsdatainput.cpp
index 69cafe3..77b999a 100644
--- a/src/runtime/api/q3dsdatainput.cpp
+++ b/src/runtime/api/q3dsdatainput.cpp
@@ -111,10 +111,11 @@ void Q3DSDataInput::setName(const QString &name)
 
     The value of this property only accounts for changes done via the same
     Q3DSDataInput instance. If the value of the same data input in the
-    presentation is changed elsewhere, for example via presentation scripting,
-    those changes are not reflected in the value of this property. Due to this
-    uncertainty, this property treats all value sets as changes even if the
-    newly set value is the same value as the previous value.
+    presentation is changed elsewhere, for example via animations or
+    Q3DSPresentation::setAttribute(), those changes are not reflected in the
+    value of this property. Due to this uncertainty, this property treats all
+    value sets as changes even if the newly set value is the same value as the
+    previous value.
 */
 QVariant Q3DSDataInput::value() const
 {
@@ -149,9 +150,54 @@ void Q3DSDataInputPrivate::sendValue()
     \instantiates Q3DSDataInput
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
-    \brief Control type for data inputs in a Qt 3D Studio presentation.
 
-    This type is a convenience type for controlling a data input in a presentation.
+    \brief Controls a data input entry in a Qt 3D Studio presentation.
+
+    This type is a convenience for controlling a data input in a presentation.
+    Its functionality is equivalent to Presentation::setDataInputValue(),
+    however it has a big advantage of being able to use QML property bindings,
+    thus avoiding the need to having to resort to a JavaScript function call
+    for every value change.
+
+    As an example, compare the following two approaches:
+
+    \qml
+        Studio3D {
+            ...
+            Presentation {
+                id: presentation
+                ...
+            }
+        }
+
+        Button {
+            onClicked: presentation.setAttribute("SomeTextNode", "textstring", "Hello World")
+        }
+    \endqml
+
+    \qml
+        Studio3D {
+            ...
+            Presentation {
+                id: presentation
+                ...
+                property string text: ""
+                DataInput {
+                    name: "inputForSomeTextNode"
+                    value: presentation.text
+                }
+            }
+        }
+
+        Button {
+            onClicked: presentation.text = "Hello World"
+        }
+    \endqml
+
+    The latter assumes that a data input connection was made in Qt 3D Studio
+    between the \c textstring property of \c SomeTextNode and a data input name
+    \c inputForSomeTextNode. As the value is now set via a property, the full
+    set of QML property bindings techniques are available.
 
     \sa Studio3D, Presentation
 */
@@ -159,22 +205,23 @@ void Q3DSDataInputPrivate::sendValue()
 /*!
     \qmlproperty string DataInput::name
 
-    Specifies the name of the controlled data input element in the presentation.
-    This property must be set as part of DataInput declaration.
+    Specifies the name of the controlled data input element in the
+    presentation. This property must be set as part of DataInput declaration,
+    although it is changeable afterwards, if desired.
 */
 
 /*!
     \qmlproperty variant DataInput::value
 
     Specifies the value of the controlled data input element in the presentation.
-    The changes to the value property are queued and handled asynchronously before the
-    next frame is displayed.
-
-    The value of this property only accounts for changes done via the same DataInput instance.
-    If the value of the same data input in the presentation is changed elsewhere,
-    for example via presentation scripting, those changes are not reflected in
-    the value of this property. Due to this uncertainty, this property treats all value sets as
-    changes even if the newly set value is the same value as the previous value.
+
+    The value of this property only accounts for changes done via the same
+    DataInput instance. If the value of the underlying attribute in the
+    presentation is changed elsewhere, for example via animations or
+    Presentation::setAttribute(), those changes are not reflected in the value
+    of this property. Due to this uncertainty, this property treats all value
+    sets as changes even if the newly set value is the same value as the
+    previous value.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dselement.cpp b/src/runtime/api/q3dselement.cpp
index 3e72e83..a09d21e 100644
--- a/src/runtime/api/q3dselement.cpp
+++ b/src/runtime/api/q3dselement.cpp
@@ -37,7 +37,7 @@ QT_BEGIN_NAMESPACE
     \inmodule 3dstudioruntime2
     \since Qt 3D Studio 2.0
 
-    \brief Controls a scene object in a Qt 3D Studio presentation.
+    \brief Controls a scene object (node) in a Qt 3D Studio presentation.
 
     This class is a convenience class for controlling the properties of a scene
     object (such as, model, material, camera, layer) in a Qt 3D Studio
@@ -183,10 +183,12 @@ void Q3DSElementPrivate::setPresentation(Q3DSPresentation *pres)
     \ingroup 3dstudioruntime2
     \brief Control type for elements in a Qt 3D Studio presentation.
 
-    This type is a convenience type for managing a presentation element.
+    This type is a convenience for controlling the properties of a scene object
+    (such as, model, material, camera, layer) in a Qt 3D Studio presentation.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    \note The functionality of Element is equivalent to
+    Presentation::setAttribute(), Presentation::getAttribute() and
+    Presentation::fireEvent().
 
     \sa Studio3D, Presentation, SceneElement
 */
@@ -195,37 +197,54 @@ void Q3DSElementPrivate::setPresentation(Q3DSPresentation *pres)
     \qmlproperty string Element::elementPath
 
     Holds the element path of the presentation element.
-    This property must be set as part of Element declaration.
-    You can specify an element of a sub-presentation by adding "SubPresentationId:"
-    in front of the element path, for example \c{"SubPresentationOne:Scene"}.
-*/
 
-/*!
-    \qmlmethod void Element::setAttribute(string attributeName, variant value)
+    An element path refers to an object in the scene either by name or id. The
+    latter is rarely used in application code since the unique IDs are not
+    exposed in the Qt 3D Studio application. To refer to an object by id,
+    prepend \c{#} to the name. Applications will typically refer to objects by
+    name.
 
-    Sets the \a value of an attribute on an element specified by this instance.
-    The \a attributeName is the \l{Attribute Names}{scripting name} of the attribute.
+    Names are not necessarily unique, however. To access an object with a
+    non-unique name, the path can be specified, for example,
+    \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+    the scene contains other layers with the default camera names (for instance
+    \c{Scene.Layer2.Camera}).
 
-    The attribute must be preserved for scripting to be set by this function, or else it will fail.
-    An attribute is preserved if it is either \e{animated}, or
-    \e{an attribute on a master element that is unlinked and changed per-slide}.
+    If the object is renamed to a unique name in the Qt 3D Studio application's
+    Timeline view, the path can be omitted. For example, if the camera in
+    question was renamed to \c MyCamera, applications can then simply pass \c
+    MyCamera as the element path.
+
+    To access an object in a sub-presentation, prepend the name of the
+    sub-presentation followed by a colon, for example,
+    \c{SubPresentationOne:Scene.Layer.Camera}.
 */
 
 /*!
-    \qmlmethod void Element::fireEvent(string eventName)
+    \qmlmethod variant Element::getAttribute(string attributeName)
+
+    Returns the current value of an attribute (property) of the scene object
+    specified by this Element instance. The \a attributeName is the
+    \l{Attribute Names}{scripting name} of the attribute.
+ */
 
-    Dispatches an event with \a eventName on the element specified by this instance.
-    Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
-    method in attached scripts will be executed in response to the event.
+/*!
+    \qmlmethod void Element::setAttribute(string attributeName, variant value)
+
+    Sets the \a value of an attribute (property) of the scene object specified
+    by this Element instance. The \a attributeName is the \l{Attribute
+    Names}{scripting name} of the attribute.
 */
 
 /*!
-    \qmlsignal Element::elementPathChanged(string elementPath)
+    \qmlmethod void Element::fireEvent(string eventName)
 
-    This signal is emitted when the element path property changes.
-    The new value is provided in the \a elementPath parameter.
+    Dispatches an event with \a eventName on the scene object
+    specified by elementPath.
 
-    The corresponding handler is \c onElementPathChanged.
+    Appropriate actions created in Qt 3D Studio or callbacks registered using
+    the registerForEvent() method in attached \c{behavior scripts} will be
+    executed in response to the event.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dspresentation.cpp b/src/runtime/api/q3dspresentation.cpp
index 0a797b2..3a8a055 100644
--- a/src/runtime/api/q3dspresentation.cpp
+++ b/src/runtime/api/q3dspresentation.cpp
@@ -128,6 +128,25 @@ void Q3DSPresentation::setSource(const QUrl &source)
     emit sourceChanged();
 }
 
+/*!
+    \property Q3DSPresentation::profilingEnabled
+
+    When enabled, Qt 3D objects managed by the runtime get tracked,
+    and various statistics get collected internally. These are then
+    exposed in the views that can be toggled by profileUiVisible.
+
+    The default value is \c false.
+
+    \note Changing the value after the presentation has been loaded
+    has no effect for the already loaded presentation. Therefore the
+    changing of this property must happen before calling setSource().
+
+    \note In the Qt 3D Studio Viewer application presentations are
+    opened with profiling enabled by default. Therefore, applications
+    wishing to have an experience comparable to the Viewer, when it
+    comes to the debug and profile views, should set this property to
+    \c true.
+*/
 bool Q3DSPresentation::isProfilingEnabled() const
 {
     Q_D(const Q3DSPresentation);
@@ -149,6 +168,17 @@ void Q3DSPresentation::setProfilingEnabled(bool enable)
     }
 }
 
+/*!
+    \property Q3DSPresentation::profileUiVisible
+
+    When this property is \c{true}, the interactive statistics and profile
+    view is displayed in-scene, on top of the 3D content.
+
+    \note This feature can be disabled at build time, in which case this
+    property has no effect.
+
+    Default value is \c{false}.
+*/
 bool Q3DSPresentation::isProfileUiVisible() const
 {
     Q_D(const Q3DSPresentation);
@@ -166,6 +196,13 @@ void Q3DSPresentation::setProfileUiVisible(bool visible)
     }
 }
 
+/*!
+    \property Q3DSPresentation::profileUiScale
+
+    Controls the scale factor of the in-scene debug and profile views.
+
+    The default value is 1.0.
+*/
 float Q3DSPresentation::profileUiScale() const
 {
     Q_D(const Q3DSPresentation);
@@ -216,10 +253,11 @@ void Q3DSPresentation::setDataInputValue(const QString &name, const QVariant &va
 }
 
 /*!
-    Dispatches an event with \a eventName on a specific element found in \a
-    elementPath. Appropriate actions created in Qt 3D Studio or callbacks
-    registered using the registerForEvent() method in attached (behavior)
-    scripts will be executed in response to the event.
+    Dispatches a Qt 3D Studio presentation event with \a eventName on
+    scene object specified by \a elementPath. These events provide a
+    way to communicate with the \c .qml based \c{behavior scripts}
+    attached to scene objects since they can register to be notified
+    via Behavior::registerForEvent().
 
     See setAttribute() for a description of \a elementPath.
  */
@@ -371,10 +409,54 @@ void Q3DSPresentation::setAttribute(const QString &elementPath, const QString &a
         d->controller->handleSetAttribute(elementPath, attributeName, value);
 }
 
+/*!
+    \fn void Q3DSPresentation::customSignalEmitted(const QString &elementPath, const QString &name)
+
+    This signal is emitted when an action with the \c{Emit Signal}
+    handler is executed in the Qt 3D Studio presentation. \a
+    elementPath specifies the scene object on which the (Qt 3D Studio)
+    "signal" \a name was triggered.
+
+    Connecting to this signal offers a way of reacting upon certain
+    events in the Qt 3D Studio presentation.
+
+    \image customsignal.png
+
+    In this example, pressing or tapping on the Cluster object will result in
+    emitting \c{customSignalEmitted("Cluster", "clusterPressed")}.
+*/
+
+/*!
+    \fn Q3DSPresentation::slideEntered(const QString &elementPath, int index, const QString &name)
+
+    This signal is emitted when a slide is entered in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the entered slide. The \a index and \a name contain the index and
+    the name of the entered slide.
+*/
+
+/*!
+    \fn Q3DSPresentation::slideExited(const QString &elementPath, int index, const QString &name)
+
+    This signal is emitted when a slide is exited in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the exited slide. The \a index and \a name contain the index and the
+    name of the exited slide.
+*/
+
 // These event forwarders are not stricly needed, Studio3D et al are fine
 // without them. However, they are there in 3DS1 and can become handy to feed
 // arbitrary, application-generated events into the engine.
 
+/*!
+    Passes a key press event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::keyPressEvent(QKeyEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -382,6 +464,15 @@ void Q3DSPresentation::keyPressEvent(QKeyEvent *e)
         d->controller->handlePresentationKeyPressEvent(e);
 }
 
+/*!
+    Passes a key release event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -389,6 +480,15 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
         d->controller->handlePresentationKeyReleaseEvent(e);
 }
 
+/*!
+    Passes a mouse press event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::mousePressEvent(QMouseEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -396,6 +496,15 @@ void Q3DSPresentation::mousePressEvent(QMouseEvent *e)
         d->controller->handlePresentationMousePressEvent(e);
 }
 
+/*!
+    Passes a mouse move event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::mouseMoveEvent(QMouseEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -403,6 +512,15 @@ void Q3DSPresentation::mouseMoveEvent(QMouseEvent *e)
         d->controller->handlePresentationMouseMoveEvent(e);
 }
 
+/*!
+    Passes a mouse release event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::mouseReleaseEvent(QMouseEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -410,6 +528,15 @@ void Q3DSPresentation::mouseReleaseEvent(QMouseEvent *e)
         d->controller->handlePresentationMouseReleaseEvent(e);
 }
 
+/*!
+    Passes a mouse double click event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::mouseDoubleClickEvent(QMouseEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -418,6 +545,15 @@ void Q3DSPresentation::mouseDoubleClickEvent(QMouseEvent *e)
 }
 
 #if QT_CONFIG(wheelevent)
+/*!
+    Passes a mouse wheel event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::wheelEvent(QWheelEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -426,6 +562,15 @@ void Q3DSPresentation::wheelEvent(QWheelEvent *e)
 }
 #endif
 
+/*!
+    Passes a touch event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::touchEvent(QTouchEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -434,6 +579,15 @@ void Q3DSPresentation::touchEvent(QTouchEvent *e)
 }
 
 #if QT_CONFIG(tabletevent)
+/*!
+    Passes a tablet (pen) event \a e to the presentation.
+
+    \note The event forwarders in Q3DSPresentation are not normally
+    needed since Q3DSWidget and Studio3D both pass mouse, keyboard and
+    touch input on to the Qt 3D Studio engine. They may become useful
+    however with Q3DSSurfaceViewer, or in special situations, in order
+    to inject input events.
+*/
 void Q3DSPresentation::tabletEvent(QTabletEvent *e)
 {
     Q_D(Q3DSPresentation);
@@ -476,12 +630,76 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
 
-    \brief Control type for Qt 3D Studio presentations.
+    \brief Represents a Qt 3D Studio presentation.
+
+    This class provides properties and methods for controlling a
+    presentation.
+
+    Qt 3D Studio supports multiple presentations in one project. There is
+    always a main presentation and zero or more sub-presentations. The
+    sub-presentations are composed into the main presentations either as
+    contents of Qt 3D Studio layers or as texture maps.
 
-    This type provides properties and methods for controlling a presentation.
+    In the filesystem each presentation corresponds to one \c{.uip}
+    file. When present, the \c{.uia} file ties these together by
+    specifying a name for each of the (sub-)presentations and
+    specifies which one is the main one.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    From the API point of view Presentation corresponds to the main
+    presentation. The source property can refer either to a \c{.uia} or
+    \c{.uip} file. When specifying a file with \c{.uip} extension and a
+    \c{.uia} is present with the same name, the \c{.uia} is loaded
+    automatically and thus sub-presentation information is available
+    regardless.
+
+    The Presentation type handles child objects of the types \l Element, \l
+    SceneElement, \l DataInput, and \l SubPresentationSettings specially. These
+    will get automatically associated with the presentation and can control
+    certain aspects of it from that point on.
+
+    \section2 Example usage
+
+    \qml
+    Studio3D {
+        Presentation {
+            id: presentation
+
+            source: "qrc:/presentation/barrel.uip"
+            profilingEnabled: true
+
+            onSlideEntered: console.log("Entered slide " + name + "(index " + index + ") on " + elementPath)
+            onSlideExited: console.log("Exited slide " + name + "(index " + index + ") on " + elementPath)
+            onCustomSignalEmitted: console.log("Got custom signal " + name)
+
+            DataInput {
+                name: "di_text"
+                value: "hello world"
+            }
+
+            SceneElement {
+                elementPath: "SomeComponentNode"
+                onCurrentSlideIndexChanged: console.log("Current slide index for component: " + currentSlideIndex)
+                onCurrentSlideNameChanged: console.log("Current slide name for component: " + currentSlideName)
+            }
+
+            SubPresentationSettings {
+                qmlStreams: [
+                    QmlStream {
+                        presentationId: "sub-presentation-id"
+                        Rectangle {
+                            width: 1024
+                            height: 1024
+                            color: "red"
+                        }
+                    }
+                ]
+            }
+        }
+    }
+    Button {
+        onClicked: presentation.setAttribute("SomeMaterial", "diffuse", "0 1 0");
+    }
+    \endqml
 
     \sa Studio3D
 */
@@ -489,22 +707,53 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlproperty url Presentation::source
 
-    Holds the presentation source (\c{*.uia} or \c{*.uip}) file location.
+    Holds the main presentation source (\c{*.uia} or \c{*.uip}) file location.
     May be either a file URL or a qrc URL.
 */
 
 /*!
-    \qmlproperty SubPresentationSettings Presentation::subPresentationSettings
+    \qmlproperty bool Presentation::profilingEnabled
+
+    When enabled, Qt 3D objects managed by the runtime get tracked,
+    and various statistics get collected internally. These are then
+    exposed in the views that can be toggled by profileUiVisible.
+
+    The default value is \c false.
+
+    \note Changing the value after the presentation has been loaded
+    has no effect for the already loaded presentation.
+
+    \note In the Qt 3D Studio Viewer application presentations are
+    opened with profiling enabled by default. Therefore, applications
+    wishing to have an experience comparable to the Viewer, when it
+    comes to the debug and profile views, should set this property to
+    \c true.
+*/
+
+/*!
+    \qmlproperty bool Presentation::profileUiVisible
+
+    When this property is \c{true}, the interactive statistics and profile
+    view is displayed in-scene, on top of the 3D content.
+
+    \note This feature can be disabled at build time, in which case this
+    property has no effect.
+
+    Default value is \c{false}.
+*/
+
+/*!
+    \qmlproperty real Presentation::profileUiScale
 
-    Holds the settings for the subpresentations in the Qt 3D Studio presentation.
+    Controls the scale factor of the in-scene debug and profile views.
 
-    This property is read-only.
+    The default value is 1.0.
 */
 
 /*!
     \qmlmethod void Presentation::goToSlide(string elementPath, string name)
 
-    Requests a time context (a Scene or a Component element) to change to a specific slide
+    Requests a time context (a Scene or a Component node) to change to a specific slide
     by \a name. If the context is already on that slide playback will start over.
 
     If \a elementPath points to a time context, that element is controlled. For
@@ -516,7 +765,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToSlide(string elementPath, int index)
 
-    Requests a time context (a Scene or a Component element) to change to a specific slide by
+    Requests a time context (a Scene or a Component node) to change to a specific slide by
     index \a index. If the context is already on that slide playback will start over.
 
     If \a elementPath points to a time context, that element is controlled. For
@@ -528,7 +777,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToSlide(string elementPath, bool next, bool wrap)
 
-    Requests a time context (a Scene or a Component element) to change to the next or the
+    Requests a time context (a Scene or a Component node) to change to the next or the
     previous slide, depending on the value of \a next. If the context is already at the
     last or first slide, \a wrap defines if change occurs to the opposite end.
 
@@ -541,7 +790,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToTime(string elementPath, real time)
 
-    Sets a time context (a Scene or a Component element) to a specific playback \a time in seconds.
+    Sets a time context (a Scene or a Component node) to a specific playback \a time in seconds.
 
     If \a elementPath points to a time context, that element is controlled. For
     all other element types the time context owning that element is controlled instead.
@@ -564,88 +813,108 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 */
 
 /*!
-    \qmlmethod void Presentation::setAttribute(string elementPath, string attributeName,
-                                               variant value)
-
-    Sets the \a value of an attribute on an element found at \a elementPath. The \a attributeName is
-    the \l{Attribute Names}{scripting name} of the attribute.
+    \qmlmethod variant Presentation::getAttribute(string elementPath, string attributeName)
 
-    You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
-    front of the element path, for example \c{"SubPresentationOne:Scene.Mesh.Material"}.
-
-    The attribute must be preserved for scripting to be set by this function, or else it will fail.
-    An attribute is preserved if it is either \e{animated}, or
-    \e{an attribute on a master element that is unlinked and changed per-slide}.
+    Returns the value of an attribute (property) on the object specified by \a
+    elementPath. The \a attributeName is the \l{Attribute Names}{scripting
+    name} of the attribute.
 */
 
 /*!
-    \qmlmethod void Presentation::setPresentationActive(string id, bool active)
-
-    Stops or starts updates to a sub-presentation based on the \a active flag. The presentation is
-    referenced to by the \a id, which is the name of the presentation without the \c{.uip}.
+    \qmlmethod void Presentation::setAttribute(string elementPath, string attributeName,
+                                               variant value)
 
-    Making a presentation inactive prevents any elements, behaviors, and animations within it from
-    updating. It also prevents any events within that presentation from being processed. It does
-    not, however, prevent the presentation from rendering. An inactive presentation will continue
-    to render using its last-updated information.
+    Sets the \a value of an attribute (property) on the Qt 3D Studio scene
+    object specified by \a elementPath. The \a attributeName is the
+    \l{Attribute Names}{scripting name} of the attribute.
 
-    Explicitly inactivating presentations can provide a significant performance increase, depending
-    on the number and size of the presentations that are inactive. Inactive presentations are not
-    ‘paused’. When the presentation is re-activated, animations will resume at the time they should
-    be had they been running, not where they were when the presentation was made inactive.
-*/
+    An element path refers to an object in the scene either by name or id. The
+    latter is rarely used in application code since the unique IDs are not
+    exposed in the Qt 3D Studio application. To refer to an object by id,
+    prepend \c{#} to the name. Applications will typically refer to objects by
+    name.
 
-/*!
-    \qmlmethod void Presentation::fireEvent(string elementPath, string eventName)
+    Names are not necessarily unique, however. To access an object with a
+    non-unique name, the path can be specified, for example,
+    \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+    the scene contains other layers with the default camera names (for instance
+    \c{Scene.Layer2.Camera}).
 
-    Dispatches an event with \a eventName on a specific element found in \a elementPath. Appropriate
-    Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
-    method in attached scripts will be executed in response to the event.
+    If the object is renamed to a unique name in the Qt 3D Studio application's
+    Timeline view, the path can be omitted. For example, if the camera in
+    question was renamed to \c MyCamera, applications can then simply pass \c
+    MyCamera as the element path.
 
-    You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
-    front of the element path, for example \c{"SubPresentationOne:Scene.Mesh"}.
+    To access an object in a sub-presentation, prepend the name of the
+    sub-presentation followed by a colon, for example,
+    \c{SubPresentationOne:Scene.Layer.Camera}.
 */
 
 /*!
-    \qmlmethod void Presentation::setGlobalAnimationTime(int64 milliseconds)
+    \qmlmethod void Presentation::fireEvent(string elementPath, string eventName)
 
-    Sets the global animation time to \a milliseconds. Setting the global animation time to a
-    non-zero value will disable the automatic animation timer. Setting the value to zero
-    resumes automatic animation timer.
+    Dispatches a Qt 3D Studio presentation event with \a eventName on
+    scene object specified by \a elementPath. These events provide a
+    way to communicate with the \c .qml based \c{behavior scripts}
+    attached to scene objects since they can register to be notified
+    via Behavior::registerForEvent().
 */
 
 /*!
     \qmlmethod void Presentation::setDataInputValue(string name, variant value)
-    \since QtStudio3D 1.1
 
     Sets the \a value of a data input element \a name in the presentation.
+
+    Data input provides a higher level, designer-driven alternative to
+    setAttribute or Element. Instead of exposing a large set of properties with
+    their intenal engine names, data input allows designers to decide which
+    properties should be writable by the application, and can assign custom
+    names to these data input entries, thus forming a well-defined contract
+    between the designer and the developer.
+
+    In addition, data input also allows controlling the time line and the
+    current slide for time context objects (Scene or Component). Therefore it
+    is also an alternative to the goToSlide, goToTime, and SceneElement.
+
+    As an alternative to this method, the \l DataInput type can be used. That
+    approach has the advantage of being able to use QML property bindings for
+    the value, instead of having to resort to JavaScript function calls for
+    every value change.
 */
 
 /*!
-    \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
+    \qmlsignal Presentation::customSignalEmitted(string elementPath, string name)
+
+    This signal is emitted when an action with the \c{Emit Signal}
+    handler is executed in the Qt 3D Studio presentation. \a
+    elementPath specifies the scene object on which the (Qt 3D Studio)
+    "signal" \a name was triggered.
+
+    Connecting to this signal offers a way of reacting upon certain
+    events in the Qt 3D Studio presentation.
+
+    \image customsignal.png
 
-    This signal is emitted when a slide is entered in the presentation.
-    The \a elementPath specifies the time context (a Scene or a Component element) owning the
-    entered slide.
-    The \a index and \a name contain the index and the name of the entered slide.
+    In this example, pressing or tapping on the Cluster object will result in
+    emitting \c{customSignalEmitted("Cluster", "clusterPressed")}.
 */
 
 /*!
-    \qmlsignal Presentation::slideExited(string elementPath, int index, string name)
+    \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
 
-    This signal is emitted when a slide is exited in the presentation.
-    The \a elementPath specifies the time context (a Scene or a Component element) owning the
-    exited slide.
-    The \a index and \a name contain the index and the name of the exited slide.
+    This signal is emitted when a slide is entered in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the entered slide. The \a index and \a name contain the index and
+    the name of the entered slide.
 */
 
 /*!
-    \qmlsignal Presentation::sourceChanged(url source)
-
-    This signal is emitted when the source property has changed.
-    The new value is provided in the \a source parameter.
+    \qmlsignal Presentation::slideExited(string elementPath, int index, string name)
 
-    The corresponding handler is \c onSourceChanged.
+    This signal is emitted when a slide is exited in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the exited slide. The \a index and \a name contain the index and the
+    name of the exited slide.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dssceneelement.cpp b/src/runtime/api/q3dssceneelement.cpp
index 6b3c161..cb7482b 100644
--- a/src/runtime/api/q3dssceneelement.cpp
+++ b/src/runtime/api/q3dssceneelement.cpp
@@ -95,7 +95,7 @@ Q3DSSceneElement::~Q3DSSceneElement()
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
-    the default slide may stil be emitted before the slide changes to the
+    the default slide may still be emitted before the slide changes to the
     desired one. This happens in order to ensure we end up with the index of
     the slide that is actually shown even if the slide specified in the initial
     declaration is invalid.
@@ -126,7 +126,7 @@ int Q3DSSceneElement::previousSlideIndex() const
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
-    the default slide may stil be emitted before the slide changes to the
+    the default slide may still be emitted before the slide changes to the
     desired one. This happens in order to ensure we end up with the index of
     the slide that is actually shown even if the slide specified in the initial
     declaration is invalid.
@@ -252,13 +252,14 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     \inherits Element
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
-    \brief Control type for scene and component elements in a Qt 3D Studio presentation.
 
-    This type is a convenience type for managing the slides of a single
-    time context (a Scene or a Component element) of a presentation.
+    \brief Controls the special Scene or Component scene objects in a Qt 3D
+    Studio presentation.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    This type is a convenience for controlling the properties of Scene
+    and Component objects in the scene. These are special since they have a
+    time context, meaning they control a timline and a set of associated
+    slides.
 
     \sa Studio3D, Presentation, Element
 */
@@ -272,11 +273,12 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     value will not actually change until the next frame has been processed, and
     even then only if the new slide was valid.
 
-    \note If this property is set to something else than the default slide for the scene at the
-    initial declaration of SceneElement, you will still get an extra changed signal for the
-    default slide before the slide changes to the desired one. This happens in order to ensure
-    we end up with the index of the slide that is actually shown even if the slide specified in the
-    initial declaration is invalid.
+    \note If this property is set to something else than the default slide for
+    the scene at the initial declaration of SceneElement, a changed signal for
+    the default slide may still be emitted before the slide changes to the
+    desired one. This happens in order to ensure we end up with the index of
+    the slide that is actually shown even if the slide specified in the initial
+    declaration is invalid.
 */
 
 /*!
@@ -296,11 +298,12 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     value will not actually change until the next frame has been processed, and
     even then only if the new slide was valid.
 
-    \note If this property is set to something else than the default slide for the scene at the
-    initial declaration of SceneElement, you will still get an extra changed signal for the
-    default slide before the slide changes to the desired one. This happens in order to ensure
-    we end up with the name of the slide that is actually shown even if the slide specified in the
-    initial declaration is invalid.
+    \note If this property is set to something else than the default slide for
+    the scene at the initial declaration of SceneElement, a changed signal for
+    the default slide may still be emitted before the slide changes to the
+    desired one. This happens in order to ensure we end up with the index of
+    the slide that is actually shown even if the slide specified in the initial
+    declaration is invalid.
 */
 
 /*!
@@ -358,9 +361,10 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
 /*!
     \qmlmethod void SceneElement::goToSlide(bool next, bool wrap)
 
-    Requests a time context (a Scene or a Component element) to change to the next or the
-    previous slide, depending on the value of \a next. If the context is already at the
-    last or first slide, \a wrap defines if change occurs to the opposite end.
+    Requests a time context (a Scene or a Component object) to change to the
+    next or previous slide, depending on the value of \a next. If the context
+    is already at the last or first slide, \a wrap defines if wrapping over to
+    the first or last slide, respectively, occurs.
 */
 
 /*!
diff --git a/src/runtime/api/q3dssurfaceviewer.cpp b/src/runtime/api/q3dssurfaceviewer.cpp
index 8ecb6c3..bbe6344 100644
--- a/src/runtime/api/q3dssurfaceviewer.cpp
+++ b/src/runtime/api/q3dssurfaceviewer.cpp
@@ -176,6 +176,11 @@ bool Q3DSSurfaceViewerPrivate::doCreate(QSurface *s, QOpenGLContext *c, uint id,
     return createEngine();
 }
 
+/*!
+    Releases the presentation and all related resources.
+
+    The Q3DSSurfaceViewer instance can be reused by calling create() again.
+ */
 void Q3DSSurfaceViewer::destroy()
 {
     Q_D(Q3DSSurfaceViewer);
@@ -188,6 +193,19 @@ void Q3DSSurfaceViewer::destroy()
 }
 
 /*!
+    \fn Q3DSSurfaceViewer::frameUpdate()
+
+    This signal is emitted each time a frame has been rendered.
+*/
+
+/*!
+    \fn Q3DSSurfaceViewer::presentationLoaded()
+
+    This signal is emitted when the viewer has been initialized and the
+    presentation is ready to be shown.
+*/
+
+/*!
     Returns the presentation object used by the Q3DSSurfaceViewer.
 */
 Q3DSPresentation *Q3DSSurfaceViewer::presentation() const
@@ -205,6 +223,15 @@ Q3DSViewerSettings *Q3DSSurfaceViewer::settings() const
     return d->viewerSettings;
 }
 
+/*!
+    \property Q3DSSurfaceViewer::error
+
+    Contains the text for the error message that was generated during the
+    loading of the presentation. When no error occurred or there is no
+    presentation loaded, the value is an empty string.
+
+    This property is read-only.
+ */
 QString Q3DSSurfaceViewer::error() const
 {
     Q_D(const Q3DSSurfaceViewer);
@@ -225,6 +252,14 @@ bool Q3DSSurfaceViewer::isRunning() const
     return d->engine && d->sourceLoaded;
 }
 
+/*!
+    \property Q3DSSurfaceViewer::size
+
+    Holds the desired size of the presentation. Relevant only when
+    autoSize is set to \c false.
+
+    \sa autoSize
+*/
 QSize Q3DSSurfaceViewer::size() const
 {
     Q_D(const Q3DSSurfaceViewer);
diff --git a/src/runtime/api/q3dsviewersettings.cpp b/src/runtime/api/q3dsviewersettings.cpp
index a0d91ea..c6c65fd 100644
--- a/src/runtime/api/q3dsviewersettings.cpp
+++ b/src/runtime/api/q3dsviewersettings.cpp
@@ -66,6 +66,32 @@ Q3DSViewerSettings::~Q3DSViewerSettings()
 {
 }
 
+/*!
+    \enum Q3DSViewerSettings::ShadeMode
+
+    This enumeration specifies the possible shading modes.
+
+    \value ShadeModeShaded The objects in the presentation are shaded normally.
+    \value ShadeModeShadedWireframe The objects in the presentation are shaded
+    with a super-imposed wireframe on top of the normal shading. Only objects that specify
+    a tesselation mode will display this wireframe.
+*/
+
+/*!
+    \enum Q3DSViewerSettings::ScaleMode
+
+    This enumeration specifies the possible scaling modes.
+
+    \value ScaleModeFit Scales the presentation to fit the viewer.
+    \value ScaleModeFill Scales the presentation to fill the viewer.
+    \value ScaleModeCenter Centers the presentation into the viewer without scaling it.
+*/
+
+/*!
+    \property Q3DSViewerSettings::matteColor
+
+    \note This property is currently ignored.
+ */
 QColor Q3DSViewerSettings::matteColor() const
 {
     Q_D(const Q3DSViewerSettings);
@@ -75,7 +101,7 @@ QColor Q3DSViewerSettings::matteColor() const
 /*!
     \property Q3DSViewerSettings::showRenderStats
 
-    If this property is set to \c{true}, the interactive statistics and profile
+    When this property is \c{true}, the interactive statistics and profile
     view is displayed in-scene, on top of the 3D content.
 
     \note This feature can be disabled at build time, in which case this
@@ -89,12 +115,22 @@ bool Q3DSViewerSettings::isShowingRenderStats() const
     return d->showRenderStats;
 }
 
+/*!
+    \property Q3DSViewerSettings::shadeMode
+
+    \note This property is currently ignored.
+ */
 Q3DSViewerSettings::ShadeMode Q3DSViewerSettings::shadeMode() const
 {
     Q_D(const Q3DSViewerSettings);
     return d->shadeMode;
 }
 
+/*!
+    \property Q3DSViewerSettings::scaleMode
+
+    \note This property is currently ignored.
+ */
 Q3DSViewerSettings::ScaleMode Q3DSViewerSettings::scaleMode() const
 {
     Q_D(const Q3DSViewerSettings);
@@ -140,6 +176,12 @@ void Q3DSViewerSettings::setScaleMode(Q3DSViewerSettings::ScaleMode mode)
     }
 }
 
+/*!
+    Persistently saves the viewer \l{QSettings}{settings} using \a group, \a organization and
+    \a application.
+
+    \note This function is not currently implemented.
+ */
 void Q3DSViewerSettings::save(const QString &group,
                               const QString &organization,
                               const QString &application)
@@ -150,6 +192,12 @@ void Q3DSViewerSettings::save(const QString &group,
     qWarning() << Q_FUNC_INFO << "not implemented";
 }
 
+/*!
+    Loads previously saved viewer \l{QSettings}{settings} using \a group, \a organization and
+    \a application.
+
+    \note This function is not currently implemented.
+ */
 void Q3DSViewerSettings::load(const QString &group,
                               const QString &organization,
                               const QString &application)
@@ -175,9 +223,13 @@ void Q3DSViewerSettings::load(const QString &group,
 /*!
     \qmlproperty bool ViewerSettings::showRenderStats
 
-    If this property is set to \c{true}, render statistics are displayed on the upper part
-    of the viewer.
-    Default value is \c{false}.
+    If this property is set to \c true, the interactive statistics and profile
+    view is displayed in-scene, on top of the 3D content.
+
+    \note this feature can be disabled at build time, in which case this
+    property has no effect.
+
+    The default value is \c{false}.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dswidget.cpp b/src/runtime/api/q3dswidget.cpp
index 8cdd898..56d65d5 100644
--- a/src/runtime/api/q3dswidget.cpp
+++ b/src/runtime/api/q3dswidget.cpp
@@ -89,7 +89,24 @@ Q3DSWidget::~Q3DSWidget()
 }
 
 /*!
+    \fn Q3DSWidget::frameUpdate()
+
+    This signal is emitted each time a frame has been rendered.
+*/
+
+/*!
+    \fn Q3DSWidget::presentationLoaded()
+
+    This signal is emitted when the viewer has been initialized and the
+    presentation is ready to be shown.
+*/
+
+/*!
+    \property Q3DSWidget::presentation
+
     Returns the presentation object used by the Q3DSWidget.
+
+    This property is read-only.
  */
 Q3DSPresentation *Q3DSWidget::presentation() const
 {
@@ -106,6 +123,15 @@ Q3DSViewerSettings *Q3DSWidget::settings() const
     return d->viewerSettings;
 }
 
+/*!
+    \property Q3DSWidget::error
+
+    Contains the text for the error message that was generated during the
+    loading of the presentation. When no error occurred or there is no
+    presentation loaded, the value is an empty string.
+
+    This property is read-only.
+ */
 QString Q3DSWidget::error() const
 {
     Q_D(const Q3DSWidget);
@@ -159,6 +185,9 @@ void Q3DSWidget::setUpdateInterval(int interval)
     }
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::keyPressEvent(QKeyEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -166,6 +195,9 @@ void Q3DSWidget::keyPressEvent(QKeyEvent *event)
         d->engine->handleKeyPressEvent(event);
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::keyReleaseEvent(QKeyEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -173,6 +205,9 @@ void Q3DSWidget::keyReleaseEvent(QKeyEvent *event)
         d->engine->handleKeyReleaseEvent(event);
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::mousePressEvent(QMouseEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -180,6 +215,9 @@ void Q3DSWidget::mousePressEvent(QMouseEvent *event)
         d->engine->handleMousePressEvent(event);
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::mouseMoveEvent(QMouseEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -187,6 +225,9 @@ void Q3DSWidget::mouseMoveEvent(QMouseEvent *event)
         d->engine->handleMouseMoveEvent(event);
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::mouseReleaseEvent(QMouseEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -194,6 +235,9 @@ void Q3DSWidget::mouseReleaseEvent(QMouseEvent *event)
         d->engine->handleMouseReleaseEvent(event);
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::mouseDoubleClickEvent(QMouseEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -202,6 +246,9 @@ void Q3DSWidget::mouseDoubleClickEvent(QMouseEvent *event)
 }
 
 #if QT_CONFIG(wheelevent)
+/*!
+    \internal
+ */
 void Q3DSWidget::wheelEvent(QWheelEvent *event)
 {
     Q_D(Q3DSWidget);
@@ -210,10 +257,16 @@ void Q3DSWidget::wheelEvent(QWheelEvent *event)
 }
 #endif
 
+/*!
+    \internal
+ */
 void Q3DSWidget::initializeGL()
 {
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::resizeGL(int w, int h)
 {
     Q_D(Q3DSWidget);
@@ -224,6 +277,9 @@ void Q3DSWidget::resizeGL(int w, int h)
     }
 }
 
+/*!
+    \internal
+ */
 void Q3DSWidget::paintGL()
 {
     Q_D(Q3DSWidget);