Revision control
Copy as Markdown
// Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include "qblendedclipanimator.h"
#include "qblendedclipanimator_p.h"
#include <Qt3DAnimation/qabstractclipblendnode.h>
#include <Qt3DAnimation/qchannelmapper.h>
#include <Qt3DAnimation/qclock.h>
QT_BEGIN_NAMESPACE
namespace Qt3DAnimation {
QBlendedClipAnimatorPrivate::QBlendedClipAnimatorPrivate()
: Qt3DAnimation::QAbstractClipAnimatorPrivate()
, m_blendTreeRoot(nullptr)
{
}
/*!
\qmltype BlendedClipAnimator
\nativetype Qt3DAnimation::QBlendedClipAnimator
\inqmlmodule Qt3D.Animation
\inherits AbstractClipAnimator
\since 5.9
\brief BlendedClipAnimator is a component providing animation playback capabilities of a tree
of blend nodes.
An instance of BlendedClipAnimator can be aggregated by an Entity to add the ability to play
back animation clips and to apply the calculated animation values to properties of QObjects.
Whereas a ClipAnimator gets its animation data from a single animation clip,
BlendedClipAnimator can blend together multiple clips. The animation data is obtained by
evaluating a so called \e {blend tree}. A blend tree is a hierarchical tree structure where the
leaf nodes are value nodes that encapsulate an animation clip (AbstractAnimationClip); and the
internal nodes represent blending operations that operate on the nodes pointed to by their
operand properties.
To associate a blend tree with a BlendedClipAnimator, set the animator's blendTree property to
point at the root node of your blend tree:
\badcode
BlendedClipAnimator {
blendTree: AdditiveClipBlend {
....
}
}
\endcode
A blend tree can be constructed from the following node types:
\note The blend node tree should only be edited when the animator is not running.
\list
\li Qt3D.Animation.ClipBlendValue
\li Qt3D.Animation.LerpClipBlend
\li Qt3D.Animation.AdditiveClipBlend
\endlist
Additional node types will be added over time.
As an example consider the following blend tree:
\badcode
Clip0----
|
Lerp Node----
| |
Clip1---- Additive Node
|
Clip2----
\endcode
This can be created and used as follows:
\badcode
BlendedClipAnimator {
blendTree: AdditiveClipBlend {
baseClip: LerpClipBlend {
startClip: ClipBlendValue {
clip: AnimationClipLoader { source: "walk.json" }
}
endClip: ClipBlendValue {
clip: AnimationClipLoader { source: "run.json" }
}
}
additiveClip: ClipBlendValue {
clip: AnimationClipLoader { source: "wave-arm.json" }
}
}
channelMapper: ChannelMapper {...}
running: true
}
\endcode
By authoring a set of animation clips and blending between them dynamically at runtime with a
blend tree, we open up a huge set of possible resulting animations. As some simple examples of
the above blend tree, where alpha is the additive factor and beta is the lerp blend factor we
can get a 2D continuum of possible animations:
\badcode
(alpha = 0, beta = 1) Running, No arm waving --- (alpha = 1, beta = 1) Running, Arm waving
| |
| |
| |
(alpha = 0, beta = 0) Walking, No arm waving --- (alpha = 0, beta = 1) Running, No arm waving
\endcode
More complex blend trees offer even more flexibility for combining your animation clips. Note
that the values used to control the blend tree (alpha and beta above) are simple properties on
the blend nodes. This means, that these properties themselves can also be controlled by
the animation framework.
*/
/*!
\class Qt3DAnimation::QBlendedClipAnimator
\inherits Qt3DAnimation::QAbstractClipAnimator
\inmodule Qt3DAnimation
\since 5.9
\brief QBlendedClipAnimator is a component providing animation playback capabilities of a tree
of blend nodes.
An instance of QBlendedClipAnimator can be aggregated by a QEntity to add the ability to play
back animation clips and to apply the calculated animation values to properties of QObjects.
Whereas a QClipAnimator gets its animation data from a single animation clip,
QBlendedClipAnimator can blend together multiple clips. The animation data is obtained by
evaluating a so called \e {blend tree}. A blend tree is a hierarchical tree structure where the
leaf nodes are value nodes that encapsulate an animation clip (QAbstractAnimationClip); and the
internal nodes represent blending operations that operate on the nodes pointed to by their
operand properties.
To associate a blend tree with a QBlendedClipAnimator, set the animator's blendTree property to
point at the root node of your blend tree:
\badcode
auto blendTreeRoot = new QAdditiveClipBlend();
...
auto animator = new QBlendedClipAnimator();
animator->setBlendTree(blendTreeRoot);
\endcode
A blend tree can be constructed from the following node types:
\note The blend node tree should only be edited when the animator is not running.
\list
\li Qt3DAnimation::QClipBlendValue
\li Qt3DAnimation::QLerpClipBlend
\li Qt3DAnimation::QAdditiveClipBlend
\endlist
Additional node types will be added over time.
As an example consider the following blend tree:
\badcode
Clip0----
|
Lerp Node----
| |
Clip1---- Additive Node
|
Clip2----
\endcode
This can be created and used as follows:
\code
// Create leaf nodes of blend tree
auto clip0 = new QClipBlendValue(
new QAnimationClipLoader(QUrl::fromLocalFile("walk.json")));
auto clip1 = new QClipBlendValue(
new QAnimationClipLoader(QUrl::fromLocalFile("run.json")));
auto clip2 = new QClipBlendValue(
new QAnimationClipLoader(QUrl::fromLocalFile("wave-arm.json")));
// Create blend tree inner nodes
auto lerpNode = new QLerpClipBlend();
lerpNode->setStartClip(clip0);
lerpNode->setEndClip(clip1);
lerpNode->setBlendFactor(0.5f); // Half-walk, half-run
auto additiveNode = new QAdditiveClipBlend();
additiveNode->setBaseClip(lerpNode); // Comes from lerp sub-tree
additiveNode->setAdditiveClip(clip2);
additiveNode->setAdditiveFactor(1.0f); // Wave arm fully
// Run the animator
auto animator = new QBlendedClipAnimator();
animator->setBlendTree(additiveNode);
animator->setChannelMapper(...);
animator->setRunning(true);
\endcode
By authoring a set of animation clips and blending between them dynamically at runtime with a
blend tree, we open up a huge set of possible resulting animations. As some simple examples of
the above blend tree, where alpha is the additive factor and beta is the lerp blend factor we
can get a 2D continuum of possible animations:
\badcode
(alpha = 0, beta = 1) Running, No arm waving --- (alpha = 1, beta = 1) Running, Arm waving
| |
| |
| |
(alpha = 0, beta = 0) Walking, No arm waving --- (alpha = 0, beta = 1) Running, No arm waving
\endcode
More complex blend trees offer even more flexibility for combining your animation clips. Note
that the values used to control the blend tree (alpha and beta above) are simple properties on
the blend nodes. This means, that these properties themselves can also be controlled by
the animation framework.
*/
QBlendedClipAnimator::QBlendedClipAnimator(Qt3DCore::QNode *parent)
: Qt3DAnimation::QAbstractClipAnimator(*new QBlendedClipAnimatorPrivate, parent)
{
}
/*! \internal */
QBlendedClipAnimator::QBlendedClipAnimator(QBlendedClipAnimatorPrivate &dd, Qt3DCore::QNode *parent)
: Qt3DAnimation::QAbstractClipAnimator(dd, parent)
{
}
QBlendedClipAnimator::~QBlendedClipAnimator()
{
}
/*!
\qmlproperty AbstractClipBlendNode Qt3D.Animation::BlendedClipAnimator::blendTree
This property holds the root of the animation blend tree that will
be evaluated before being interpolated by the animator.
*/
/*!
\property Qt3DAnimation::QBlendedClipAnimator::blendTree
This property holds the root of the animation blend tree that will be evaluated before being
interpolated by the animator.
*/
QAbstractClipBlendNode *QBlendedClipAnimator::blendTree() const
{
Q_D(const QBlendedClipAnimator);
return d->m_blendTreeRoot;
}
void QBlendedClipAnimator::setBlendTree(QAbstractClipBlendNode *blendTree)
{
Q_D(QBlendedClipAnimator);
if (d->m_blendTreeRoot == blendTree)
return;
if (d->m_blendTreeRoot)
d->unregisterDestructionHelper(d->m_blendTreeRoot);
if (blendTree != nullptr && blendTree->parent() == nullptr)
blendTree->setParent(this);
d->m_blendTreeRoot = blendTree;
if (d->m_blendTreeRoot)
d->registerDestructionHelper(d->m_blendTreeRoot, &QBlendedClipAnimator::setBlendTree, d->m_blendTreeRoot);
emit blendTreeChanged(blendTree);
}
} // namespace Qt3DAnimation
QT_END_NAMESPACE
#include "moc_qblendedclipanimator.cpp"