1/****************************************************************************
2**
3** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
4** Contact: http://www.qt-project.org/legal
5**
6** This file is part of the Qt3D module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL3$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPLv3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or later as published by the Free
28** Software Foundation and appearing in the file LICENSE.GPL included in
29** the packaging of this file. Please review the following information to
30** ensure the GNU General Public License version 2.0 requirements will be
31** met: http://www.gnu.org/licenses/gpl-2.0.html.
32**
33** $QT_END_LICENSE$
34**
35****************************************************************************/
36
37#include "qadditiveclipblend.h"
38#include "qadditiveclipblend_p.h"
39#include <Qt3DAnimation/qclipblendnodecreatedchange.h>
40
41QT_BEGIN_NAMESPACE
42
43namespace Qt3DAnimation {
44
45
46/*!
47 \qmltype AdditiveClipBlend
48 \instantiates Qt3DAnimation::QAdditiveClipBlend
49 \inqmlmodule Qt3D.Animation
50
51 \since 5.9
52
53 \brief Performs an additive blend of two animation clips based on an additive factor.
54
55 QAdditiveClipBlend can be useful to create advanced animation effects based on
56 individual animation clips. For example, if you:
57
58 \list
59 \li set the baseClip property to a normal walk cycle animation clip and
60 \li set the additiveClip property to a shaking head difference clip,
61 \endlist
62
63 then adjusting the additiveFactor property will control how much of the additiveClip gets added
64 on to the baseClip. This has he effect that with an additiveFactor of zero, this blend node will
65 yield the original walk cycle clip. With an additiveFactor of 1, it will yield the walk cycle
66 including a shaking head animation.
67
68 The blending operation implemented by this class is:
69
70 \badcode
71 resultClip = baseClip + additiveFactor * additiveClip
72 \endcode
73
74 There is nothing stopping you from using values for the additiveFacor property outside the 0 to
75 1 range, but please be aware that the input animation clips may not be authored in such a way
76 for this to make sense.
77
78 \sa BlendedClipAnimator
79*/
80
81/*!
82 \class Qt3DAnimation::QAdditiveClipBlend
83 \inherits Qt3DAnimation::QAbstractClipBlendNode
84
85 \inmodule Qt3DAnimation
86 \since 5.9
87
88 \brief Performs an additive blend of two animation clips based on an additive factor.
89
90 QAdditiveClipBlend can be useful to create advanced animation effects based on
91 individual animation clips. For example, if you:
92
93 \list
94 \li set the baseClip property to a normal walk cycle animation clip and
95 \li set the additiveClip property to a shaking head difference clip,
96 \endlist
97
98 then adjusting the additiveFactor property will control how much of the additiveClip gets added
99 on to the baseClip. This has he effect that with an additiveFactor of zero, this blend node will
100 yield the original walk cycle clip. With an additiveFactor of 1, it will yield the walk cycle
101 including a shaking head animation.
102
103 The blending operation implemented by this class is:
104
105 \badcode
106 resultClip = baseClip + additiveFactor * additiveClip
107 \endcode
108
109 There is nothing stopping you from using values for the additiveFacor property outside the 0 to
110 1 range, but please be aware that the input animation clips may not be authored in such a way
111 for this to make sense.
112
113 \sa QBlendedClipAnimator
114*/
115
116QAdditiveClipBlendPrivate::QAdditiveClipBlendPrivate()
117 : QAbstractClipBlendNodePrivate()
118 , m_baseClip(nullptr)
119 , m_additiveClip(nullptr)
120 , m_additiveFactor(0.0f)
121{
122}
123
124QAdditiveClipBlend::QAdditiveClipBlend(Qt3DCore::QNode *parent)
125 : QAbstractClipBlendNode(*new QAdditiveClipBlendPrivate(), parent)
126{
127}
128
129QAdditiveClipBlend::QAdditiveClipBlend(QAdditiveClipBlendPrivate &dd, Qt3DCore::QNode *parent)
130 : QAbstractClipBlendNode(dd, parent)
131{
132}
133
134QAdditiveClipBlend::~QAdditiveClipBlend()
135{
136}
137
138Qt3DCore::QNodeCreatedChangeBasePtr QAdditiveClipBlend::createNodeCreationChange() const
139{
140 Q_D(const QAdditiveClipBlend);
141 auto creationChange = QClipBlendNodeCreatedChangePtr<QAdditiveClipBlendData>::create(this);
142 QAdditiveClipBlendData &data = creationChange->data;
143 data.baseClipId = Qt3DCore::qIdForNode(d->m_baseClip);
144 data.additiveClipId = Qt3DCore::qIdForNode(d->m_additiveClip);
145 data.additiveFactor = d->m_additiveFactor;
146 return creationChange;
147}
148
149/*!
150 \qmlproperty real AdditiveClipBlend::additiveFactor
151
152 Specifies the blending factor, typically between 0 and 1, to control the blending of
153 two animation clips.
154*/
155/*!
156 \property QAdditiveClipBlend::additiveFactor
157
158 Specifies the blending factor, typically between 0 and 1, to control the blending of
159 two animation clips.
160 */
161float QAdditiveClipBlend::additiveFactor() const
162{
163 Q_D(const QAdditiveClipBlend);
164 return d->m_additiveFactor;
165}
166
167/*!
168 \qmlproperty AbstractClipBlendNode Qt3D.Animation::AdditiveClipBlend::baseClip
169
170 This property holds the base animation clip. When the additiveFactor is zero the \a baseClip will
171 also be the resulting clip of this blend node.
172*/
173/*!
174 \property QAdditiveClipBlend::baseClip
175
176 This property holds the base animation clip. When the additiveFactor
177 is zero the baseClip will also be the resulting clip of this blend node.
178*/
179QAbstractClipBlendNode *QAdditiveClipBlend::baseClip() const
180{
181 Q_D(const QAdditiveClipBlend);
182 return d->m_baseClip;
183}
184
185/*!
186 \qmlproperty AbstractClipBlendNode Qt3D.Animation::AdditiveClipBlend::additiveClip
187
188 This property holds the additive clip to be blended with the baseClip. The amount of blending
189 is controlled by the additiveFactor property.
190*/
191/*!
192 \property QAdditiveClipBlend::additiveClip
193
194 This property holds the additive clip to be blended with the baseClip. The amount of blending
195 is controlled by the additiveFactor property.
196*/
197QAbstractClipBlendNode *QAdditiveClipBlend::additiveClip() const
198{
199 Q_D(const QAdditiveClipBlend);
200 return d->m_additiveClip;
201}
202
203void QAdditiveClipBlend::setAdditiveFactor(float additiveFactor)
204{
205 Q_D(QAdditiveClipBlend);
206 if (d->m_additiveFactor == additiveFactor)
207 return;
208
209 d->m_additiveFactor = additiveFactor;
210 emit additiveFactorChanged(additiveFactor);
211}
212
213void QAdditiveClipBlend::setBaseClip(QAbstractClipBlendNode *baseClip)
214{
215 Q_D(QAdditiveClipBlend);
216 if (d->m_baseClip == baseClip)
217 return;
218
219 if (d->m_baseClip)
220 d->unregisterDestructionHelper(d->m_baseClip);
221
222 if (baseClip && !baseClip->parent())
223 baseClip->setParent(this);
224 d->m_baseClip = baseClip;
225
226 // Ensures proper bookkeeping
227 if (d->m_baseClip)
228 d->registerDestructionHelper(d->m_baseClip, &QAdditiveClipBlend::setBaseClip, d->m_baseClip);
229
230 emit baseClipChanged(baseClip);
231}
232
233void QAdditiveClipBlend::setAdditiveClip(QAbstractClipBlendNode *additiveClip)
234{
235 Q_D(QAdditiveClipBlend);
236 if (d->m_additiveClip == additiveClip)
237 return;
238
239 if (d->m_additiveClip)
240 d->unregisterDestructionHelper(d->m_additiveClip);
241
242 if (additiveClip && !additiveClip->parent())
243 additiveClip->setParent(this);
244 d->m_additiveClip = additiveClip;
245
246 // Ensures proper bookkeeping
247 if (d->m_additiveClip)
248 d->registerDestructionHelper(d->m_additiveClip, &QAdditiveClipBlend::setAdditiveClip, d->m_additiveClip);
249 emit additiveClipChanged(additiveClip);
250}
251
252} // Qt3DAnimation
253
254QT_END_NAMESPACE
255