<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qt3danimation-module.qdoc -->
<title>Qt 3D Animation C++ Classes | Qt 3D 5.12.2</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qt3d-index.html">Qt 3D</a></td><td >Qt 3D Animation C++ Classes</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qt3d-index.html">Qt 5.12.2 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#namespaces">Namespaces</a></li>
<li class="level1"><a href="#classes">Classes</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#overview">Overview</a></li>
<li class="level2"><a href="#reference">Reference</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt 3D Animation C++ Classes</h1>
<span class="subtitle"></span>
<!-- $$$Qt3DAnimation-brief -->
<p>The Qt 3D Animation modules provides a set of prebuilt elements to help you get started with Qt 3D. <a href="#details">More...</a></p>
<!-- @@@Qt3DAnimation -->
<p><b>This module is under development and is subject to change.</b></p>
<a name="namespaces"></a>
<h2 id="namespaces">Namespaces</h2>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation.html">Qt3DAnimation</a></p></td><td class="tblDescr"><p>Contains classes from the Qt3DAnimation module</p></td></tr>
</table></div>
<a name="classes"></a>
<h2 id="classes">Classes</h2>
<div class="table"><table class="annotated">
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qabstractanimation.html">Qt3DAnimation::QAbstractAnimation</a></p></td><td class="tblDescr"><p>An abstract base class for Qt3D animations</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qabstractanimationclip.html">Qt3DAnimation::QAbstractAnimationClip</a></p></td><td class="tblDescr"><p>The base class for types providing key frame animation data</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qabstractclipanimator.html">Qt3DAnimation::QAbstractClipAnimator</a></p></td><td class="tblDescr"><p>The base class for types providing animation playback capabilities</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qabstractclipblendnode.html">Qt3DAnimation::QAbstractClipBlendNode</a></p></td><td class="tblDescr"><p>The base class for types used to construct animation blend trees</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qadditiveclipblend.html">Qt3DAnimation::QAdditiveClipBlend</a></p></td><td class="tblDescr"><p>Performs an additive blend of two animation clips based on an additive factor</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationaspect.html">Qt3DAnimation::QAnimationAspect</a></p></td><td class="tblDescr"><p>Provides key-frame animation capabilities to Qt 3D</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationclip.html">Qt3DAnimation::QAnimationClip</a></p></td><td class="tblDescr"><p>Specifies key frame animation data</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationclipdata.html">Qt3DAnimation::QAnimationClipData</a></p></td><td class="tblDescr"><p>Class containing the animation data</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationcliploader.html">Qt3DAnimation::QAnimationClipLoader</a></p></td><td class="tblDescr"><p>Enables loading key frame animation data from a file</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationcontroller.html">Qt3DAnimation::QAnimationController</a></p></td><td class="tblDescr"><p>A controller class for animations</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qanimationgroup.html">Qt3DAnimation::QAnimationGroup</a></p></td><td class="tblDescr"><p>A class grouping animations together</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qblendedclipanimator.html">Qt3DAnimation::QBlendedClipAnimator</a></p></td><td class="tblDescr"><p>Component providing animation playback capabilities of a tree of blend nodes</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qcallbackmapping.html">Qt3DAnimation::QCallbackMapping</a></p></td><td class="tblDescr"><p>Allows to map the channels within the clip onto an invocation of a callback object</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qchannelmapper.html">Qt3DAnimation::QChannelMapper</a></p></td><td class="tblDescr"><p>Allows to map the channels within the clip onto properties of objects in the application</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qchannelmapping.html">Qt3DAnimation::QChannelMapping</a></p></td><td class="tblDescr"><p>Allows to map the channels within the clip onto properties of objects in the application</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a></p></td><td class="tblDescr"><p>Component providing simple animation playback capabilities</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qclipblendnodecreatedchangebase.html">Qt3DAnimation::QClipBlendNodeCreatedChangeBase</a></p></td><td class="tblDescr"><p>Base class for changes in QClipBlendNode</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qclipblendvalue.html">Qt3DAnimation::QClipBlendValue</a></p></td><td class="tblDescr"><p>Class used for including a clip in a blend tree</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qkeyframe.html">Qt3DAnimation::QKeyFrame</a></p></td><td class="tblDescr"><p>A base class for handling keyframes</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qkeyframeanimation.html">Qt3DAnimation::QKeyframeAnimation</a></p></td><td class="tblDescr"><p>A class implementing simple keyframe animation to a QTransform</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qlerpclipblend.html">Qt3DAnimation::QLerpClipBlend</a></p></td><td class="tblDescr"><p>Performs a linear interpolation of two animation clips based on a normalized factor</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qmorphtarget.html">Qt3DAnimation::QMorphTarget</a></p></td><td class="tblDescr"><p>A class providing morph targets to blend-shape animation</p></td></tr>
<tr class="odd topAlign"><td class="tblName"><p><a href="qt3danimation-qmorphinganimation.html">Qt3DAnimation::QMorphingAnimation</a></p></td><td class="tblDescr"><p>A class implementing blend-shape morphing animation</p></td></tr>
<tr class="even topAlign"><td class="tblName"><p><a href="qt3danimation-qvertexblendanimation.html">Qt3DAnimation::QVertexBlendAnimation</a></p></td><td class="tblDescr"><p>A class implementing vertex-blend morphing animation</p></td></tr>
</table></div>
<!-- $$$Qt3DAnimation-description -->
<a name="details"></a>
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>This module is still in development but is available as a technology preview. This means it is unstable, likely to change and provided as a convenience only.</p>
<pre class="cpp">
<span class="preprocessor">#include <Qt3DAnimation></span>
</pre>
<p>To link against the corresponding C++ library, add the following to your qmake project file:</p>
<pre class="cpp plain">
QT += 3danimation
</pre>
<p>Classes, types, and functions are declared under the <a href="qt3danimation-module.html">Qt3DAnimation</a> namespace.</p>
<a name="overview"></a>
<h3 >Overview</h3>
<p>The Qt 3D Animation module adds support for specifying and using animations that can be applied to the properties of objects in your simulation. Initially this module supports key frame based animations. That is, properties have values 'keyed' at certain times and when played back the property values are calculated by interpolating between the known values within the key frames. All of the animation evaluation within the Qt 3D Animation module takes place on the Qt 3D threadpool. This allows the animations to run smoothly and to scale up to high throughput.</p>
<a name="animation-data"></a>
<h4 >Animation Data</h4>
<p>Key frame animation data can either be created programmatically via the Qt 3D Animation APIs such as Qt3DAnimation::QKeyFrameData or it can come from digital content creation (DCC) tools such as Blender, Maya or 3D Studio Max. Qt 3D provides an example export script for animation data for Blender. The format consumed by Qt 3D Animation at present is a simple JSON based format. This allows both developers and artists to easily work with animation data. More formats optimised for runtime consumption will be added later.</p>
<p>The key frame animation data can be loaded from file using the <a href="qt3danimation-qanimationcliploader.html">Qt3DAnimation::QAnimationClipLoader</a> class. To specify animation data programmatically use the <a href="qt3danimation-qanimationclip.html">Qt3DAnimation::QAnimationClip</a> class.</p>
<p>By default, the key frame data is specified using cubic bezier curves. This allows smooth animations to be created from a small number of key frame data points. Other interpolation types will be added later.</p>
<a name="playing-animations"></a>
<h4 >Playing Animations</h4>
<p>In addition to the animation data containing the key frames, Qt 3D Animation also provides APIs for playing the animations and mapping the resulting property values onto properties of objects in your simulation. There are currently two ways of playing the animations:</p>
<ul>
<li><a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a></li>
<li><a href="qt3danimation-qblendedclipanimator.html">Qt3DAnimation::QBlendedClipAnimator</a></li>
</ul>
<p>Both of these are implemented as subclasses of <a href="qt3dcore-qcomponent.html">Qt3DCore::QComponent</a> meaning that objects of these types can be aggregated by <a href="qt3dcore-qentity.html">Qt3DCore::QEntity</a> objects to add animation capabilities to your simulated entities.</p>
<a name="simple-animation-playback"></a>
<h4 >Simple Animation Playback</h4>
<p>The <a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a> class allows the playback of a single <a href="qt3danimation-qabstractanimationclip.html">Qt3DAnimation::QAbstractAnimationClip</a> at a time. To add an animation to an entity, simply add an instance of the <a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a> class to your entity's <code>components</code> property.</p>
<p>The Qt 3D Animation module takes a slightly different approach to QPropertyAnimation and <a href="qml-qt3d-animation-abstractanimation.html">AbstractAnimation</a>. With those animation frameworks, the animation specifies both the animation values <i>and</i> the target objects and properties. The animation components in Qt 3D separate these two orthogonal concepts. For example, the <a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a> component has a <code>clip</code> property for specifying the animation data (<a href="qt3danimation-qanimationclip.html">Qt3DAnimation::QAnimationClip</a> or <a href="qt3danimation-qanimationcliploader.html">Qt3DAnimation::QAnimationClipLoader</a>).</p>
<p>This allows calculation of the animated values, but more information is needed in order to map these values onto properties of objects. This is accomplished with the a <a href="qt3danimation-qchannelmapper.html">Qt3DAnimation::QChannelMapper</a> which contains a list of <a href="qt3danimation-qchannelmapping.html">Qt3DAnimation::QChannelMapping</a> objects. A <a href="qt3danimation-qchannelmapping.html">Qt3DAnimation::QChannelMapping</a> is used to map a specific channel from an animation clip onto a named property of a target object. By separating the animation data and property mappings like this, the same animation can be applied to many objects without needing to have multiple copies of the animation data or objects. It also allows animation data to easily be retargeted to other objects.</p>
<a name="blended-animation-playback"></a>
<h4 >Blended Animation Playback</h4>
<p>The <a href="qt3danimation-qblendedclipanimator.html">Qt3DAnimation::QBlendedClipAnimator</a> component allows to go beyond what is possible with <a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a> by blending several animation clips together before applying the property changes to the target properties. The animator component still takes a channel mapper just like the standard <a href="qt3danimation-qclipanimator.html">Qt3DAnimation::QClipAnimator</a> component. However, instead of specifying a single animation clip, it is necessary to set the <code>blendTree</code> property to point to the root node of a <i>blend tree</i>.</p>
<p>A blend tree is a data structure representing how animation clips get aggregated or blended together as the function of properties on the blend tree nodes. The currently supported set of blend tree nodes are:</p>
<ul>
<li><a href="qt3danimation-qclipblendvalue.html">Qt3DAnimation::QClipBlendValue</a></li>
<li><a href="qt3danimation-qlerpclipblend.html">Qt3DAnimation::QLerpClipBlend</a></li>
<li><a href="qt3danimation-qadditiveclipblend.html">Qt3DAnimation::QAdditiveClipBlend</a></li>
</ul>
<p>The source animation clip inputs are specified as leaf nodes in the blend tree using instances of the <a href="qt3danimation-qclipblendvalue.html">Qt3DAnimation::QClipBlendValue</a> class. These animation clips can be combined in a large number of ways. For now the Qt3D Animation module provides linear interpolation (LERP) and additive blend operations. More blend node types will be added over time. These are expected to include at least a generalised LERP node and a barycentric LERP node.</p>
<p>As an example consider the following blend tree:</p>
<pre class="cpp plain">
Clip0----
|
Lerp Node----
| |
Clip1---- Additive Node
|
Clip2----
</pre>
<p>Let's assume that <code>Clip0</code> represents a walk animation cycle with a duration of 3 seconds and that <code>Clip1</code> is a run animation cycle with a duration of 2 seconds. These are both inputs (and dependencies) of the <code>Lerp</code> blend node. The result of evaluating the <code>Lerp</code> node depends upon the <code>blendFactor</code> property of the <code>Lerp</code> node. This could be bound to the speed of a humanoid character entity for example. As the speed of the character increases the animation gradually cross-fades from the walk animation in <code>Clip0</code> to the run animation in <code>Clip1</code>.</p>
<p>Furthermore, let's assume that <code>Clip2</code> represents some variation animation that can be added on (waving arms or shaking head for e.g.). The amount of this additive clip that is added can be controlled by the <code>additiveFactor</code> property on the <code>Additive</code> blend node.</p>
<p>When evaluating a blend tree, normalized time (or phase) is used so that clips of different durations can be blended together without problems. For example, even though the walk and run animation clips are of different lengths, as long as they are created by the animator such that the foot-falls line up at the same phase these can be nicely interpolated.</p>
<p>The implication of this is that the duration of the blended clip is actually a function of the blend factors of the nodes in the tree. Considering only the <code>Lerp</code> node in the above example, when the blend factor of the <code>Lerp</code> node is 0, only the walk animation in Clip0 is used resulting in a duration of 3 seconds. With a blend factor of 1 the resulting duration will be 2 seconds. For intermediate blend factors, the duration will be linearly interpolated between 3 and 2 seconds.</p>
<p>By definining your own blend trees, you have complete control over how to combine your collection of input animation clips. The blend tree can be configured by the properties on the blend nodes. Note also that the properties on the blend nodes themselves are just standard properties, so these could in turn be driven by other animations if desired.</p>
<a name="reference"></a>
<h3 >Reference</h3>
<ul>
<li><a href="qt3danimation-module.html">Qt 3D Animation C++ Classes</a></li>
<li><a href="qt3d-examples.html">Qt 3D Examples</a></li>
</ul>
</div>
<!-- @@@Qt3DAnimation -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
c936229ef0138f42857f36beadbeda30
>
files
>
622
