Warning: That file was not part of the compilation database. It may have many parsing errors.

1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
5** Contact: https://www.qt.io/licensing/
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see https://www.qt.io/terms-conditions. For further
16** information use the contact form at https://www.qt.io/contact-us.
17**
18** GNU Free Documentation License Usage
19** Alternatively, this file may be used under the terms of the GNU Free
20** Documentation License version 1.3 as published by the Free Software
21** Foundation and appearing in the file included in the packaging of
22** this file. Please review the following information to ensure
23** the GNU Free Documentation License version 1.3 requirements
24** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
25** $QT_END_LICENSE$
26**
27****************************************************************************/
28
29/*!
30 \module Qt3DAnimation
31 \title Qt 3D Animation C++ Classes
32 \preliminary
33
34 \keyword Qt 3D Animation
35 \brief The Qt 3D Animation modules provides a set of prebuilt elements to help
36 you get started with Qt 3D.
37
38 This module is still in development but is available as a technology preview.
39 This means it is unstable, likely to change and provided as a convenience only.
40
41 \ingroup modules
42 \ingroup qt3d-modules-preliminary
43 \qtvariable 3danimation
44
45 \code
46 #include <Qt3DAnimation>
47 \endcode
48
49 To link against the corresponding C++ library, add the following to your qmake project file:
50
51 \badcode
52 QT += 3danimation
53 \endcode
54
55 Classes, types, and functions are declared under the \l [Qt3DAnimation]{Qt3DAnimation} namespace.
56
57 \section1 Overview
58
59 The Qt 3D Animation module adds support for specifying and using animations
60 that can be applied to the properties of objects in your simulation.
61 Initially this module supports key frame based animations. That is,
62 properties have values 'keyed' at certain times and when played back the
63 property values are calculated by interpolating between the known values
64 within the key frames. All of the animation evaluation within the Qt 3D
65 Animation module takes place on the Qt 3D threadpool. This allows the
66 animations to run smoothly and to scale up to high throughput.
67
68 \section2 Animation Data
69
70 Key frame animation data can either be created programmatically via the Qt
71 3D Animation APIs such as Qt3DAnimation::QKeyFrameData or it can come from
72 digital content creation (DCC) tools such as Blender, Maya or 3D Studio
73 Max. Qt 3D provides an example export script for animation data for
74 Blender. The format consumed by Qt 3D Animation at present is a simple JSON
75 based format. This allows both developers and artists to easily work with
76 animation data. More formats optimised for runtime consumption will be
77 added later.
78
79 The key frame animation data can be loaded from file using the
80 Qt3DAnimation::QAnimationClipLoader class. To specify animation data
81 programmatically use the Qt3DAnimation::QAnimationClip class.
82
83 By default, the key frame data is specified using cubic bezier curves. This
84 allows smooth animations to be created from a small number of key frame
85 data points. Other interpolation types will be added later.
86
87 \section2 Playing Animations
88
89 In addition to the animation data containing the key frames, Qt 3D
90 Animation also provides APIs for playing the animations and mapping the
91 resulting property values onto properties of objects in your simulation.
92 There are currently two ways of playing the animations:
93
94 \list
95 \li Qt3DAnimation::QClipAnimator
96 \li Qt3DAnimation::QBlendedClipAnimator
97 \endlist
98
99 Both of these are implemented as subclasses of Qt3DCore::QComponent meaning
100 that objects of these types can be aggregated by Qt3DCore::QEntity objects
101 to add animation capabilities to your simulated entities.
102
103 \section2 Simple Animation Playback
104
105 The Qt3DAnimation::QClipAnimator class allows the playback of a single
106 Qt3DAnimation::QAbstractAnimationClip at a time. To add an animation to an
107 entity, simply add an instance of the Qt3DAnimation::QClipAnimator class to
108 your entity's \c components property.
109
110 The Qt 3D Animation module takes a slightly different approach to
111 QPropertyAnimation and AbstractAnimation. With those animation frameworks,
112 the animation specifies both the animation values \e {and} the target
113 objects and properties. The animation components in Qt 3D separate these
114 two orthogonal concepts. For example, the Qt3DAnimation::QClipAnimator
115 component has a \c clip property for specifying the animation data
116 (Qt3DAnimation::QAnimationClip or Qt3DAnimation::QAnimationClipLoader).
117
118 This allows calculation of the animated values, but more information is
119 needed in order to map these values onto properties of objects. This is
120 accomplished with the a Qt3DAnimation::QChannelMapper which contains a list
121 of Qt3DAnimation::QChannelMapping objects. A Qt3DAnimation::QChannelMapping
122 is used to map a specific channel from an animation clip onto a named
123 property of a target object. By separating the animation data and property
124 mappings like this, the same animation can be applied to many objects
125 without needing to have multiple copies of the animation data or objects.
126 It also allows animation data to easily be retargeted to other objects.
127
128 \section2 Blended Animation Playback
129
130 The Qt3DAnimation::QBlendedClipAnimator component allows to go beyond what
131 is possible with Qt3DAnimation::QClipAnimator by blending several animation
132 clips together before applying the property changes to the target
133 properties. The animator component still takes a channel mapper just like
134 the standard Qt3DAnimation::QClipAnimator component. However, instead of
135 specifying a single animation clip, it is necessary to set the \c blendTree
136 property to point to the root node of a \e {blend tree}.
137
138 A blend tree is a data structure representing how animation clips get
139 aggregated or blended together as the function of properties on the blend
140 tree nodes. The currently supported set of blend tree nodes are:
141
142 \list
143 \li Qt3DAnimation::QClipBlendValue
144 \li Qt3DAnimation::QLerpClipBlend
145 \li Qt3DAnimation::QAdditiveClipBlend
146 \endlist
147
148 The source animation clip inputs are specified as leaf nodes in the blend
149 tree using instances of the Qt3DAnimation::QClipBlendValue class. These
150 animation clips can be combined in a large number of ways. For now the Qt3D
151 Animation module provides linear interpolation (LERP) and additive blend
152 operations. More blend node types will be added over time. These are
153 expected to include at least a generalised LERP node and a barycentric LERP
154 node.
155
156 As an example consider the following blend tree:
157
158 \badcode
159 Clip0----
160 |
161 Lerp Node----
162 | |
163 Clip1---- Additive Node
164 |
165 Clip2----
166 \endcode
167
168 Let's assume that \c Clip0 represents a walk animation cycle with a
169 duration of 3 seconds and that \c Clip1 is a run animation cycle with a
170 duration of 2 seconds. These are both inputs (and dependencies) of the \c
171 Lerp blend node. The result of evaluating the \c Lerp node depends upon the
172 \c blendFactor property of the \c Lerp node. This could be bound to the
173 speed of a humanoid character entity for example. As the speed of the
174 character increases the animation gradually cross-fades from the walk
175 animation in \c Clip0 to the run animation in \c Clip1.
176
177 Furthermore, let's assume that \c Clip2 represents some variation animation
178 that can be added on (waving arms or shaking head for e.g.). The amount of
179 this additive clip that is added can be controlled by the \c additiveFactor
180 property on the \c Additive blend node.
181
182 When evaluating a blend tree, normalized time (or phase) is used so that
183 clips of different durations can be blended together without problems. For
184 example, even though the walk and run animation clips are of different
185 lengths, as long as they are created by the animator such that the
186 foot-falls line up at the same phase these can be nicely interpolated.
187
188 The implication of this is that the duration of the blended clip is
189 actually a function of the blend factors of the nodes in the tree.
190 Considering only the \c Lerp node in the above example, when the blend
191 factor of the \c Lerp node is 0, only the walk animation in Clip0 is used
192 resulting in a duration of 3 seconds. With a blend factor of 1 the
193 resulting duration will be 2 seconds. For intermediate blend factors, the
194 duration will be linearly interpolated between 3 and 2 seconds.
195
196 By definining your own blend trees, you have complete control over how to
197 combine your collection of input animation clips. The blend tree can be
198 configured by the properties on the blend nodes. Note also that the
199 properties on the blend nodes themselves are just standard properties, so
200 these could in turn be driven by other animations if desired.
201
202 \section1 Reference
203 \list
204 \li \l {Qt 3D Animation C++ Classes}
205 \li \l {Qt 3D Examples}
206 \endlist
207 */
208
209/*!
210 \namespace Qt3DAnimation
211 \inmodule Qt3DAnimation
212 \ingroup qt3d-namespaces
213
214 \brief Contains classes from the Qt3DAnimation module.
215*/
216
217/*!
218 \qmlmodule Qt3D.Animation 2.\QtMinorVersion
219 \title Qt 3D Qt3DAnimation QML Types
220 \preliminary
221
222 \ingroup qmlmodules
223 \ingroup qt3d-qmlmodules-preliminary
224
225 \brief Provides Qt 3D QML types for the animation module.
226
227 To import and use the module's QML types, use the following statement:
228
229 \qml \QtMinorVersion
230 import Qt3D.Animation 2.\1
231 \endqml
232*/
233

Warning: That file was not part of the compilation database. It may have many parsing errors.