docs: Add recipe for animating an actor on a curved path

Show how to animate an actor using a ClutterPathConstraint.

This demonstrates how to get effects similar to
ClutterPathBehaviour with the modern animation APIs.

Includes 3 examples:

1) Simple ClutterPathConstraint used with implicit animations
2) ClutterPathConstraint used to simulate circular animation,
using ClutterAnimator
3) Creating simple curved path animations with non-linear
easing

doc/cookbook/examples/Makefile.am

@@ -11,6 +11,9 @@ noinst_PROGRAMS = \
 	animations-moving-animator		\
 	animations-moving-implicit		\
 	animations-moving-state			\
+	animations-path			\
+	animations-path-circle			\
+	animations-path-easing			\
 	animations-reuse			\
 	animations-rotating			\
 	animations-scaling			\
@@ -71,6 +74,9 @@ animations_looping_state_SOURCES           = animations-looping-state.c
 animations_moving_animator_SOURCES         = animations-moving-animator.c
 animations_moving_implicit_SOURCES         = animations-moving-implicit.c
 animations_moving_state_SOURCES            = animations-moving-state.c
+animations_path_SOURCES                    = animations-path.c
+animations_path_circle_SOURCES             = animations-path-circle.c
+animations_path_easing_SOURCES             = animations-path-easing.c
 animations_reuse_SOURCES                   = animations-reuse.c
 animations_rotating_SOURCES                = animations-rotating.c
 animations_scaling_SOURCES                 = animations-scaling.c

doc/cookbook/examples/animations-path-circle.c

@@ -0,0 +1,128 @@
+#include <stdlib.h>
+#include <clutter/clutter.h>
+
+#define STAGE_SIDE 400.0
+
+static const ClutterColor stage_color = { 0x33, 0x33, 0x55, 0xff };
+static const ClutterColor red_color = { 0xff, 0x00, 0x00, 0xff };
+
+/* Build a "circular" path out of 4 Bezier curves
+ *
+ * code modified from
+ * http://git.clutter-project.org/dax/tree/dax/dax-traverser-clutter.c#n328
+ *
+ * see http://www.whizkidtech.redprince.net/bezier/circle/
+ * for further explanation
+ */
+static ClutterPath *
+build_circular_path (gfloat cx,
+                     gfloat cy,
+                     gfloat r)
+{
+  ClutterPath *path;
+  static gfloat kappa = 4 * (G_SQRT2 - 1) / 3;
+
+  path = clutter_path_new ();
+
+  clutter_path_add_move_to (path, cx + r, cy);
+  clutter_path_add_curve_to (path,
+                             cx + r, cy + r * kappa,
+                             cx + r * kappa, cy + r,
+                             cx, cy + r);
+  clutter_path_add_curve_to (path,
+                             cx - r * kappa, cy + r,
+                             cx - r, cy + r * kappa,
+                             cx - r, cy);
+  clutter_path_add_curve_to (path,
+                             cx - r, cy - r * kappa,
+                             cx - r * kappa, cy - r,
+                             cx, cy - r);
+  clutter_path_add_curve_to (path,
+                             cx + r * kappa, cy - r,
+                             cx + r, cy - r * kappa,
+                             cx + r, cy);
+  clutter_path_add_close (path);
+
+  return path;
+}
+
+static gboolean
+key_pressed_cb (ClutterActor *actor,
+                ClutterEvent *event,
+                gpointer      user_data)
+{
+  ClutterTimeline *timeline = CLUTTER_TIMELINE (user_data);
+
+  if (!clutter_timeline_is_playing (timeline))
+    clutter_timeline_start (timeline);
+
+  return TRUE;
+}
+
+int
+main (int   argc,
+      char *argv[])
+{
+  ClutterPath *path;
+  ClutterConstraint *constraint;
+  ClutterAnimator *animator;
+  ClutterTimeline *timeline;
+  ClutterActor *stage;
+  ClutterActor *rectangle;
+
+  clutter_init (&argc, &argv);
+
+  stage = clutter_stage_new ();
+  clutter_actor_set_size (stage, STAGE_SIDE, STAGE_SIDE);
+  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
+  g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
+
+  rectangle = clutter_rectangle_new_with_color (&red_color);
+  clutter_actor_set_size (rectangle, STAGE_SIDE / 8, STAGE_SIDE / 8);
+  clutter_actor_set_position (rectangle,
+                              STAGE_SIDE / 2,
+                              STAGE_SIDE / 2);
+
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage),
+                               rectangle);
+
+  /* set up a path and make a constraint with it */
+  path = build_circular_path (STAGE_SIDE / 2,
+                              STAGE_SIDE / 2,
+                              STAGE_SIDE / 4);
+  constraint = clutter_path_constraint_new (path, 0.0);
+
+  /* apply the constraint to the rectangle; note that there
+   * is no need to name the constraint, as we will be animating
+   * the constraint's offset property directly using ClutterAnimator
+   */
+  clutter_actor_add_constraint (rectangle, constraint);
+
+  /* animation to animate the path offset */
+  animator = clutter_animator_new ();
+  clutter_animator_set_duration (animator, 5000);
+
+  /* use ClutterAnimator to animate the constraint directly */
+  clutter_animator_set (animator,
+                        constraint, "offset", CLUTTER_LINEAR, 0.0, 0.0,
+                        constraint, "offset", CLUTTER_LINEAR, 1.0, 1.0,
+                        NULL);
+
+  timeline = clutter_animator_get_timeline (animator);
+  clutter_timeline_set_loop (timeline, TRUE);
+  clutter_timeline_set_auto_reverse (timeline, TRUE);
+
+  g_signal_connect (stage,
+                    "key-press-event",
+                    G_CALLBACK (key_pressed_cb),
+                    timeline);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  /* clean up */
+  g_object_unref (animator);
+
+  return EXIT_SUCCESS;
+}

doc/cookbook/examples/animations-path-easing.c

@@ -0,0 +1,104 @@
+#include <stdlib.h>
+#include <clutter/clutter.h>
+
+typedef struct {
+  ClutterActor *red;
+  ClutterActor *green;
+  ClutterTimeline *timeline;
+} State;
+
+static const ClutterColor stage_color = { 0x33, 0x33, 0x55, 0xff };
+static const ClutterColor red_color = { 0xff, 0x00, 0x00, 0xff };
+static const ClutterColor green_color = { 0x00, 0xff, 0x00, 0xff };
+
+static void
+reverse_timeline (ClutterTimeline *timeline)
+{
+  ClutterTimelineDirection dir = clutter_timeline_get_direction (timeline);
+
+  if (dir == CLUTTER_TIMELINE_FORWARD)
+    dir = CLUTTER_TIMELINE_BACKWARD;
+  else
+    dir = CLUTTER_TIMELINE_FORWARD;
+
+  clutter_timeline_set_direction (timeline, dir);
+}
+
+/* a key press either starts the timeline or reverses it */
+static gboolean
+key_pressed_cb (ClutterActor *actor,
+                ClutterEvent *event,
+                gpointer      user_data)
+{
+  State *state = (State *) user_data;
+
+  if (clutter_timeline_is_playing (state->timeline))
+    reverse_timeline (state->timeline);
+  else
+    clutter_timeline_start (state->timeline);
+
+  return TRUE;
+}
+
+int
+main (int   argc,
+      char *argv[])
+{
+  State *state = g_new0 (State, 1);
+
+  ClutterActor *stage;
+  ClutterAnimator *animator;
+
+  clutter_init (&argc, &argv);
+
+  stage = clutter_stage_new ();
+  clutter_actor_set_size (stage, 400, 400);
+  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_color);
+  g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
+
+  state->red = clutter_rectangle_new_with_color (&red_color);
+  clutter_actor_set_size (state->red, 100, 100);
+  clutter_actor_set_position (state->red, 300, 300);
+
+  state->green = clutter_rectangle_new_with_color (&green_color);
+  clutter_actor_set_size (state->green, 100, 100);
+  clutter_actor_set_position (state->green, 0, 0);
+
+  animator = clutter_animator_new ();
+  clutter_animator_set_duration (animator, 1000);
+
+  clutter_animator_set (animator,
+                        state->red, "x", CLUTTER_LINEAR, 0.0, 300.0,
+                        state->red, "y", CLUTTER_LINEAR, 0.0, 300.0,
+                        state->red, "x", CLUTTER_LINEAR, 1.0, 0.0,
+                        state->red, "y", CLUTTER_EASE_IN_QUINT, 1.0, 0.0,
+                        NULL);
+
+  clutter_animator_set (animator,
+                        state->green, "x", CLUTTER_LINEAR, 0.0, 0.0,
+                        state->green, "y", CLUTTER_LINEAR, 0.0, 0.0,
+                        state->green, "x", CLUTTER_LINEAR, 1.0, 300.0,
+                        state->green, "y", CLUTTER_EASE_IN_QUINT, 1.0, 300.0,
+                        NULL);
+
+  state->timeline = clutter_animator_get_timeline (animator);
+
+  clutter_timeline_set_auto_reverse (state->timeline, TRUE);
+
+  g_signal_connect (stage,
+                    "key-press-event",
+                    G_CALLBACK (key_pressed_cb),
+                    state);
+
+  clutter_container_add (CLUTTER_CONTAINER (stage), state->red, state->green, NULL);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  g_object_unref (animator);
+
+  g_free (state);
+
+  return EXIT_SUCCESS;
+}

doc/cookbook/examples/animations-path.c

@@ -0,0 +1,61 @@
+#include <stdlib.h>
+#include <clutter/clutter.h>
+
+int
+main (int   argc,
+      char *argv[])
+{
+  ClutterActor *stage;
+  ClutterPath *path;
+  ClutterConstraint *constraint;
+  ClutterActor *rectangle;
+  ClutterTimeline *timeline;
+
+  const ClutterColor *stage_color = clutter_color_new (51, 51, 85, 255);
+  const ClutterColor *red_color = clutter_color_new (255, 0, 0, 255);
+
+  clutter_init (&argc, &argv);
+
+  stage = clutter_stage_new ();
+  clutter_actor_set_size (stage, 360, 300);
+  clutter_stage_set_color (CLUTTER_STAGE (stage), stage_color);
+  g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
+
+  /* create the path */
+  path = clutter_path_new ();
+  clutter_path_add_move_to (path, 30, 60);
+
+  /* add a curve round to the top-right of the stage */
+  clutter_path_add_rel_curve_to (path,
+                                 120, 180,
+                                 180, 120,
+                                 240, 0);
+
+  /* create a constraint based on the path */
+  constraint = clutter_path_constraint_new (path, 0.0);
+
+  /* put a rectangle at the start of the path */
+  rectangle = clutter_rectangle_new_with_color (red_color);
+  clutter_actor_set_size (rectangle, 60, 60);
+
+  /* add the constraint to the rectangle */
+  clutter_actor_add_constraint_with_name (rectangle, "path", constraint);
+
+  /* add the rectangle to the stage */
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), rectangle);
+
+  /* set up the timeline */
+  timeline = clutter_timeline_new (1000);
+  clutter_timeline_set_loop (timeline, TRUE);
+  clutter_timeline_set_auto_reverse (timeline, TRUE);
+
+  clutter_actor_animate_with_timeline (rectangle, CLUTTER_LINEAR, timeline,
+                                       "@constraints.path.offset", 1.0,
+                                       NULL);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  return EXIT_SUCCESS;
+}