1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Chapter 5. Animations</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="The Clutter Cookbook"><link rel="up" href="index.html" title="The Clutter Cookbook"><link rel="prev" href="textures-crossfade.html" title="7. Cross-fading between two images"><link rel="next" href="animations-inversion.html" title="2. Inverting Animations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Animations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="textures-crossfade.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="animations-inversion.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 5. Animations"><div class="titlepage"><div><div><h2 class="title"><a name="animations"></a>Chapter 5. Animations</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="animations.html#animations-introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="animations.html#idp8140112">1.1. High level overview</a></span></dt><dt><span class="section"><a href="animations.html#animations-introduction-alphas">1.2. Alphas</a></span></dt><dt><span class="section"><a href="animations.html#animations-introduction-api">1.3. Clutter's animation API</a></span></dt></dl></dd><dt><span class="section"><a href="animations-inversion.html">2. Inverting Animations</a></span></dt><dd><dl><dt><span class="section"><a href="animations-inversion.html#idp6035616">2.1. Problem</a></span></dt><dt><span class="section"><a href="animations-inversion.html#idp6036928">2.2. Solution</a></span></dt><dt><span class="section"><a href="animations-inversion.html#idp10795392">2.3. Discussion</a></span></dt></dl></dd><dt><span class="section"><a href="animations-fading.html">3. Fading an actor out of or into view</a></span></dt><dd><dl><dt><span class="section"><a href="animations-fading.html#idp10803808">3.1. Problem</a></span></dt><dt><span class="section"><a href="animations-fading.html#idp10805120">3.2. Solution</a></span></dt><dt><span class="section"><a href="animations-fading.html#idp10822160">3.3. Discussion</a></span></dt></dl></dd><dt><span class="section"><a href="animations-rotating.html">4. Rotating an actor</a></span></dt><dd><dl><dt><span class="section"><a href="animations-rotating.html#idp10825616">4.1. Problem</a></span></dt><dt><span class="section"><a href="animations-rotating.html#idp10830192">4.2. Solution</a></span></dt><dt><span class="section"><a href="animations-rotating.html#idp10857376">4.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-rotating.html#idp10918480">4.4. Full example</a></span></dt></dl></dd><dt><span class="section"><a href="animations-complex.html">5. Creating complex animations with
2
<span class="type">ClutterAnimator</span></a></span></dt><dd><dl><dt><span class="section"><a href="animations-complex.html#idp10929936">5.1. Problem</a></span></dt><dt><span class="section"><a href="animations-complex.html#idp10932064">5.2. Solution</a></span></dt><dt><span class="section"><a href="animations-complex.html#animations-complex-discussion">5.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-complex.html#idp11250384">5.4. Full example</a></span></dt></dl></dd><dt><span class="section"><a href="animations-reuse.html">6. Reusing a complex animation on different actors</a></span></dt><dd><dl><dt><span class="section"><a href="animations-reuse.html#animations-reuse-problem">6.1. Problem</a></span></dt><dt><span class="section"><a href="animations-reuse.html#animations-reuse-solution">6.2. Solution</a></span></dt><dt><span class="section"><a href="animations-reuse.html#animations-reuse-discussion">6.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-reuse.html#animations-reuse-examples">6.4. Full example</a></span></dt></dl></dd><dt><span class="section"><a href="animations-moving.html">7. Moving actors</a></span></dt><dd><dl><dt><span class="section"><a href="animations-moving.html#idp11336784">7.1. Problem</a></span></dt><dt><span class="section"><a href="animations-moving.html#idp11341152">7.2. Solutions</a></span></dt><dt><span class="section"><a href="animations-moving.html#idp11362816">7.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-moving.html#animations-moving-examples">7.4. Full examples</a></span></dt></dl></dd><dt><span class="section"><a href="animations-looping.html">8. Looping an animation</a></span></dt><dd><dl><dt><span class="section"><a href="animations-looping.html#idp11444480">8.1. Problem</a></span></dt><dt><span class="section"><a href="animations-looping.html#idp11445712">8.2. Solutions</a></span></dt><dt><span class="section"><a href="animations-looping.html#idp11491184">8.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-looping.html#animations-looping-examples">8.4. Full examples</a></span></dt></dl></dd><dt><span class="section"><a href="animations-scaling.html">9. Animated scaling</a></span></dt><dd><dl><dt><span class="section"><a href="animations-scaling.html#idp11534512">9.1. Problem</a></span></dt><dt><span class="section"><a href="animations-scaling.html#idp11537920">9.2. Solution</a></span></dt><dt><span class="section"><a href="animations-scaling.html#idp11544704">9.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-scaling.html#animations-scaling-examples">9.4. Full examples</a></span></dt></dl></dd><dt><span class="section"><a href="animations-path.html">10. Animating an actor along a curved path</a></span></dt><dd><dl><dt><span class="section"><a href="animations-path.html#idp11606304">10.1. Problem</a></span></dt><dt><span class="section"><a href="animations-path.html#idp11607584">10.2. Solution</a></span></dt><dt><span class="section"><a href="animations-path.html#idp11622752">10.3. Discussion</a></span></dt><dt><span class="section"><a href="animations-path.html#animations-path-examples">10.4. Full examples</a></span></dt></dl></dd></dl></div><div class="epigraph"><p>Animation can explain whatever the mind of man can conceive.</p><div class="attribution"><span>—<span class="attribution">Walt Disney</span></span></div></div><div class="section" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="animations-introduction"></a>1. Introduction</h2></div></div></div><p>Clutter actors have a variety of <span class="emphasis"><em>properties</em></span>
3
(position, size, rotation in 3D space, scale, opacity) which govern
4
their visual appearance in the UI. They may also have
5
<span class="emphasis"><em>constraints</em></span> on how they are aligned
6
and/or positioned relative to each other.</p><p>The Clutter animation API provides a means of changing
7
properties and constraints as a function of time: moving, scaling,
8
rotating, changing opacity and colour, modifying postional
9
constraints, etc.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Clutter also makes it possible to animate non-visual
10
properties if desired.</p></div><div class="section" title="1.1. High level overview"><div class="titlepage"><div><div><h3 class="title"><a name="idp8140112"></a>1.1. High level overview</h3></div></div></div><p>Here are the main concepts behind animation in Clutter:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>An <span class="emphasis"><em>animation</em></span> changes one or more
11
properties of one or more actors over time: their rotation in
12
a particular dimension (<code class="varname">x</code>, <code class="varname">y</code>,
13
<code class="varname">z</code>), scale, size, opacity etc.</p></li><li class="listitem"><p>An animation has an associated <span class="emphasis"><em>timeline</em></span>.
14
Think of this as analogous to the "thing" you're controlling when
15
you watch a video on the internet: it's what you control with
16
the play/pause button and what is measured by the bar
17
showing how far through the video you are. As with the
18
controls on a video player, you can play/pause/skip a Clutter
19
timeline; you can also rewind it, loop it, and play it
20
backwards.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If a timeline is reversed, the progress along the
21
timeline is still measured the same way as it is in the forward
22
direction: so if you start from the end of the timeline and run
23
it backwards for 75% of its length, the progress is reported
24
as 0.25 (i.e. 25% of the way from the start of the
25
timeline).</p></div></li><li class="listitem"><p>The <span class="emphasis"><em>duration</em></span> of a timeline
26
(e.g. 500 milliseconds, 1 second, 10 seconds) specifies how
27
long its animation will last. The timeline can be inspected
28
to find out how much of it has elapsed, either as a value in
29
milliseconds or as a fraction (between 0 and 1) of the total
30
length of the timeline.</p></li><li class="listitem"><p>An animation is divided into <span class="emphasis"><em>frames</em></span>.
31
The number of frames which make up the animation isn't
32
constant: it depends on various factors, like how powerful
33
your machine is, the state of the drivers for your hardware,
34
and the load on he system. So you won't always get the same
35
number of frames in an animation of a particular duration.</p></li><li class="listitem"><p>The change to a property in an animation occurs over
36
the course of the timeline: the start value of the property
37
heads toward some target value. When it reaches the end of
38
the timeline, the property should have reached the target
39
value.</p></li><li class="listitem"><p>Exactly how the property changes over the course of the
40
timeline is governed by an <span class="emphasis"><em>alpha</em></span>. This
41
is the trickiest idea to explain, so it has its own section
42
below.</p></li></ul></div></div><div class="section" title="1.2. Alphas"><div class="titlepage"><div><div><h3 class="title"><a name="animations-introduction-alphas"></a>1.2. Alphas</h3></div></div></div><p>An alpha is generated for each frame of the animation.
43
The alpha varies between -1.0 and 2.0, and changes during the
44
course of the animation's timeline; ideally, the value should
45
start at 0.0 and reach 1.0 by the end of the timeline.</p><p>The alpha for any given frame of the animation is determined
46
by an <span class="emphasis"><em>alpha function</em></span>. Usually, the alpha
47
function will return a value based on progress along the timeline.
48
However, the alpha function doesn't have to respect or pay
49
attention to the timeline: it can be entirely random if desired.</p><p>To work out the value of a property at a given frame
50
somewhere along the timeline for a given alpha:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Determine the difference between the start value and
51
the target end value for the property.</p></li><li class="listitem"><p>Multiply the difference by the alpha for the current
52
frame.</p></li><li class="listitem"><p>Add the result to the start value.</p></li></ol></div><p>The shape of the plot of the alpha function over time is
53
called its <span class="emphasis"><em>easing mode</em></span>. Clutter provides
54
various modes ranging from <code class="constant">CLUTTER_LINEAR</code>
55
(the alpha value is equal to progress along the timeline),
56
to modes based on various polynomial and exponential functions,
57
to modes providing elastic and bounce shapes. See the
58
ClutterAlpha documentation for examples of the shapes produced
59
by these functions. There is also a good interactive demo
61
<a class="ulink" href="http://www.robertpenner.com/easing/easing_demo.html" target="_top">Robert Penner's site</a>.
62
</p><p>Most of the time, you can use the built-in Clutter easing
63
modes to get the kind of animation effect you want. However,
64
in some cases you may want to provide your own alpha function.
65
Here's an example (based on the quintic ease in mode from
66
<code class="filename">clutter-alpha.c</code>):</p><div class="informalexample"><pre class="programlisting">static gdouble
67
_alpha_ease_in_sextic (ClutterAlpha *alpha,
68
gpointer dummy G_GNUC_UNUSED)
70
ClutterTimeline *timeline = clutter_alpha_get_timeline (alpha);
71
gdouble p = clutter_timeline_get_progress (timeline);
73
return p * p * p * p * p * p;
74
}</pre></div><p>An alpha function just has to have a specified method
75
signature and return a <span class="type">gdouble</span> value when called.
76
As stated above, you'd typically base the return value on the
77
timeline progress; the function above shows how you get the
78
timeline associated with the alpha, so you can apply the alpha
79
function to it.</p></div><div class="section" title="1.3. Clutter's animation API"><div class="titlepage"><div><div><h3 class="title"><a name="animations-introduction-api"></a>1.3. Clutter's animation API</h3></div></div></div><p>All of the animation approaches in Clutter use the same
80
basic underpinnings (as explained above), but the API provides
81
varying levels of abstraction and/or ease of use on top of those
82
underpinnings.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Implicit animations</em></span> (created using
83
<code class="function">clutter_actor_animate()</code> and related
84
functions) are useful where you want to apply
85
a simple or one-off animation to an actor. They enable you
86
to animate one or more properties using a single easing mode;
87
however, you only specify the target values for the properties
88
you're animating, not the start values.</p></li><li class="listitem"><p><span class="emphasis"><em>ClutterAnimator</em></span> provides support
89
for declarative animations (defined using <span class="type">ClutterScript</span>).
90
You can animate multiple actors with this approach, and
91
have more control over the easing modes used during an
92
animation: while implicit animations only allow a single
93
easing mode for all properties, <span class="type">ClutterAnimator</span>
94
supports <span class="emphasis"><em>multiple</em></span> easing modes for
95
<span class="emphasis"><em>each</em></span> property; <span class="emphasis"><em>key frames</em></span>
96
are used to indicate where in the animation each easing mode
97
should be applied.</p></li><li class="listitem"><p><span class="emphasis"><em>ClutterState</em></span> enables you to describe
98
<span class="emphasis"><em>states</em></span>: property values across one or
99
more actors, plus the easing modes used to transition to
100
those values. It can also be combined with <span class="type">ClutterAnimator</span>
101
for finer grained definition of transitions if desired.</p><p>States are particularly useful if you need actors to
102
animate between a known set of positions/sizes/opacities etc.
103
during their lifecycles (e.g. animating a list of items in
104
a menu, or for animations in a picture viewer where you
105
click on thumbnails to display a full view of a photograph).</p></li></ul></div><p>The recipes in this section show when and where it is
106
appropriate to use each of these approaches.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="textures-crossfade.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="animations-inversion.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7. Cross-fading between two images </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2. Inverting Animations</td></tr></table></div></body></html>