diff --git a/doc/cookbook/animations.xml b/doc/cookbook/animations.xml
index 1c310060a..2cc0cdaae 100644
--- a/doc/cookbook/animations.xml
+++ b/doc/cookbook/animations.xml
@@ -5,14 +5,211 @@
Animations
- the author of the epigraph
- a short epigraph
+ Walt Disney
+ Animation can explain whatever the mind of man can conceive.
Introduction
- introduction
+ Clutter actors have a variety of properties
+ (position, size, rotation in 3D space, scale, opacity) which govern
+ their visual appearance in the UI. They may also have
+ constraints on how they are aligned
+ and/or positioned relative to each other.
+
+ The Clutter animation API provides a means of changing
+ properties and constraints as a function of time: moving, scaling,
+ rotating, changing opacity and colour, modifying postional
+ constraints, etc.
+
+ Clutter also makes it possible to animate non-visual
+ properties if desired.
+
+
+ High level overview
+
+ Here are the main concepts behind animation in Clutter:
+
+
+
+ An animation changes one or more
+ properties of one or more actors over time: their rotation in
+ a particular dimension (x, y,
+ z), scale, size, opacity etc.
+
+
+ An animation has an associated timeline.
+ Think of this as analogous to the "thing" you're controlling when
+ you watch a video on the internet: it's what you control with
+ the play/pause button and what is measured by the bar
+ showing how far through the video you are. As with the
+ controls on a video player, you can play/pause/skip a Clutter
+ timeline; you can also rewind it, loop it, and play it
+ backwards.
+
+ If a timeline is reversed, the progress along the
+ timeline is still measured the same way as it is in the forward
+ direction: so if you start from the end of the timeline and run
+ it backwards for 75% of its length, the progress is reported
+ as 0.25 (i.e. 25% of the way from the start of the
+ timeline).
+
+
+
+ The duration of a timeline
+ (e.g. 500 milliseconds, 1 second, 10 seconds) specifies how
+ long its animation will last. The timeline can be inspected
+ to find out how much of it has elapsed, either as a value in
+ milliseconds or as a fraction (between 0 and 1) of the total
+ length of the timeline.
+
+
+ An animation is divided into frames.
+ The number of frames which make up the animation isn't
+ constant: it depends on various factors, like how powerful
+ your machine is, the state of the drivers for your hardware,
+ and the load on he system. So you won't always get the same
+ number of frames in an animation of a particular duration.
+
+
+ The change to a property in an animation occurs over
+ the course of the timeline: the start value of the property
+ heads toward some target value. When it reaches the end of
+ the timeline, the property should have reached the target
+ value.
+
+
+ Exactly how the property changes over the course of the
+ timeline is governed by an alpha. This
+ is the trickiest idea to explain, so it has its own section
+ below.
+
+
+
+
+
+ Alphas
+
+ An alpha is generated for each frame of the animation.
+ The alpha varies between -1.0 and 2.0, and changes during the
+ course of the animation's timeline; ideally, the value should
+ start at 0.0 and reach 1.0 by the end of the timeline.
+
+ The alpha for any given frame of the animation is determined
+ by an alpha function. Usually, the alpha
+ function will return a value based on progress along the timeline.
+ However, the alpha function doesn't have to respect or pay
+ attention to the timeline: it can be entirely random if desired.
+
+ To work out the value of a property at a given frame
+ somewhere along the timeline for a given alpha:
+
+
+
+ Determine the difference between the start value and
+ the target end value for the property.
+
+
+ Multiply the difference by the alpha for the current
+ frame.
+
+
+ Add the result to the start value.
+
+
+
+ The shape of the plot of the alpha function over time is
+ called its easing mode. Clutter provides
+ various modes ranging from CLUTTER_LINEAR
+ (the alpha value is equal to progress along the timeline),
+ to modes based on various polynomial and exponential functions,
+ to modes providing elastic and bounce shapes. See the
+ ClutterAlpha documentation for examples of the shapes produced
+ by these functions. There is also a good interactive demo
+ of the modes on
+ Robert Penner's site.
+
+
+ Most of the time, you can use the built-in Clutter easing
+ modes to get the kind of animation effect you want. However,
+ in some cases you may want to provide your own alpha function.
+ Here's an example (based on the quintic ease in mode from
+ clutter-alpha.c):
+
+
+
+
+
+
+
+ An alpha function just has to have a specified method
+ signature and return a gdouble value when called.
+ As stated above, you'd typically base the return value on the
+ timeline progress; the function above shows how you get the
+ timeline associated with the alpha, so you can apply the alpha
+ function to it.
+
+
+
+ Clutter's animation API
+
+ All of the animation approaches in Clutter use the same
+ basic underpinnings (as explained above), but the API provides
+ varying levels of abstraction and/or ease of use on top of those
+ underpinnings.
+
+
+
+ Implicit animations (created using
+ clutter_actor_animate() and related
+ functions) are useful where you want to apply
+ a simple or one-off animation to an actor. They enable you
+ to animate one or more properties using a single easing mode;
+ however, you only specify the target values for the properties
+ you're animating, not the start values.
+
+
+ ClutterAnimator provides support
+ for declarative animations (defined using ClutterScript).
+ You can animate multiple actors with this approach, and
+ have more control over the easing modes used during an
+ animation: while implicit animations only allow a single
+ easing mode for all properties, ClutterAnimator
+ supports multiple easing modes for
+ each property; key frames
+ are used to indicate where in the animation each easing mode
+ should be applied.
+
+
+ ClutterState enables you to describe
+ states: property values across one or
+ more actors, plus the easing modes used to transition to
+ those values. It can also be combined with ClutterAnimator
+ for finer grained definition of transitions if desired.
+ States are particularly useful if you need actors to
+ animate between a known set of positions/sizes/opacities etc.
+ during their lifecycles (e.g. animating a list of items in
+ a menu, or for animations in a picture viewer where you
+ click on thumbnails to display a full view of a photograph).
+
+
+
+ The recipes in this section show when and where it is
+ appropriate to use each of these approaches.
+
+
+