Document QAbstractAnimationClip

Change-Id: Iec70236a5af333a0149d229b6c9d528629fa3107
Reviewed-by: Mike Krus <mike.krus@kdab.com>
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

1 files changed, 86 insertions, 0 deletions

diff --git a/src/animation/frontend/qabstractanimationclip.cpp b/src/animation/frontend/qabstractanimationclip.cpp
index 5fdf7ae68..435155465 100644
--- a/src/animation/frontend/qabstractanimationclip.cpp
+++ b/src/animation/frontend/qabstractanimationclip.cpp
@@ -60,22 +60,108 @@ void QAbstractAnimationClipPrivate::setDuration(float duration)
     q->blockNotifications(wasBlocked);
 }
 
+/*!
+    \class Qt3DAnimation::QAbstractAnimationClip
+    \inherits Qt3DCore::QNode
+
+    \inmodule Qt3DAnimation
+    \since 5.9
+
+    \brief QAbstractAnimationClip is the base class for types providing key frame animation data.
+
+    To utilise the key frame animation framework in the Qt 3D Animation module
+    the animator component in use needs to be provided with the key frame animation data. The
+    animation data is provided by one of the concrete subclasses of QAbstractAnimationClip:
+
+    \list
+    \li Qt3DAnimation::QAnimationClip
+    \li Qt3DAnimation::QAnimationClipLoader
+    \endlist
+
+    QAnimationClip should be used when you want to create the animation data
+    programmatically within your application. The actual data is set with a
+    QAnimationClipData value type.
+
+    If you are loading baked animation data from a file, e.g. as created by an
+    artist, then use the QAnimationClipLoader class and set its \c source property.
+
+    Once the animation clip has been populated with data using the above
+    methods, the read-only duration property will be updated by the Qt 3D Animation
+    backend.
+
+    The typical usage of animation clips is:
+
+    \code
+    auto animator = new QClipAnimator();
+    auto clip = new QAnimationClipLoader();
+    clip->setSource(QUrl::fromLocalFile("bounce.json"));
+    animator->setClip(clip);
+    animator->setChannelMapper(...);
+    animator->setRunning(true);
+    \endcode
+
+    Animation clips are also used as the leaf node values in animation blend trees:
+
+    \code
+    // Create first leaf node of blend tree
+    auto slideClip = new QAnimationClipLoader();
+    slideClip->setSource(QUrl::fromLocalFile("slide.json"));
+    auto slideClipValue = new QClipBlendValue();
+    slideClipValue->setClip(slideClip);
+
+    // Create second leaf node of blend tree
+    auto bounceClip = new QAnimationClipLoader();
+    bounceClip->setSource(QUrl::fromLocalFile("bounce.json"));
+    auto bounceClipValue = new QClipBlendValue();
+    bounceClipValue->setClip(bounceClip);
+
+    // Create blend tree inner node
+    auto additiveNode = new QAdditiveClipBlend();
+    additiveNode->setBaseClip(slideClipValue);
+    additiveNode->setAdditiveClip(bounceClipValue);
+    additiveNode->setAdditiveFactor(0.5f);
+
+    // Run the animator
+    auto animator = new QBlendedClipAnimator();
+    animator->setBlendTree(additiveNode);
+    animator->setChannelMapper(...);
+    animator->setRunning(true);
+    \endcode
+
+    \sa QAnimationClip, QAnimationClipLoader
+*/
+
+/*!
+    \internal
+*/
 QAbstractAnimationClip::QAbstractAnimationClip(QAbstractAnimationClipPrivate &dd,
                                                Qt3DCore::QNode *parent)
     : Qt3DCore::QNode(dd, parent)
 {
 }
 
+/*!
+    Destroys this animation clip.
+*/
 QAbstractAnimationClip::~QAbstractAnimationClip()
 {
 }
 
+/*!
+    \property QAbstractAnimationClip::duration
+
+    Holds the duration of the animation clip in seconds. Gets updated once the
+    animation data is provided to Qt 3D using one of the concrete subclasses.
+*/
 float QAbstractAnimationClip::duration() const
 {
     Q_D(const QAbstractAnimationClip);
     return d->m_duration;
 }
 
+/*!
+    \internal
+*/
 void QAbstractAnimationClip::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change)
 {
     Q_D(QAbstractAnimationClip);