clutter/clutter-keyframe-transition.c

   1 /*
   2  * Clutter.
   3  *
   4  * An OpenGL based 'interactive canvas' library.
   5  *
   6  * Copyright (C) 2012 Intel Corporation
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  20  *
  21  * Author: Emmanuele Bassi <ebassi@linux.intel.com>
  22  */
  23
  24 /**
  25  * SECTION:clutter-keyframe-transition
  26  * @Title: ClutterKeyframeTransition
  27  * @Short_Description: Keyframe property transition
  28  *
  29  * #ClutterKeyframeTransition allows animating a property by defining
  30  * "key frames": values at a normalized position on the transition
  31  * duration.
  32  *
  33  * The #ClutterKeyframeTransition interpolates the value of the property
  34  * to which it's bound across these key values.
  35  *
  36  * Setting up a #ClutterKeyframeTransition means providing the times,
  37  * values, and easing modes between these key frames, for instance:
  38  *
  39  * |[
  40  *   ClutterTransition *keyframe;
  41  *
  42  *   keyframe = clutter_keyframe_transition_new ("opacity");
  43  *   clutter_transition_set_from (keyframe, G_TYPE_UINT, 255);
  44  *   clutter_transition_set_to (keyframe, G_TYPE_UINT, 0);
  45  *   clutter_keyframe_transition_set_keys (CLUTTER_KEYFRAME_TRANSITION (keyframe),
  46  *                                         G_TYPE_UINT,
  47  *                                         1, /&ast; number of key frames &ast;/
  48  *                                         0.5, 128, CLUTTER_EASE_IN_OUT_CUBIC);
  49  * ]|
  50  *
  51  * The example above sets up a keyframe transition for the #ClutterActor:opacity
  52  * property of a #ClutterActor; the transition starts and sets the value of the
  53  * property to fully transparent; between the start of the transition and its mid
  54  * point, it will animate the property to half opacity, using an easy in/easy out
  55  * progress. Once the transition reaches the mid point, it will linearly fade the
  56  * actor out until it reaches the end of the transition.
  57  *
  58  * The #ClutterKeyframeTransition will add an implicit key frame between the last
  59  * and the 1.0 value, to interpolate to the final value of the transition's
  60  * interval.
  61  *
  62  * #ClutterKeyframeTransition is available since Clutter 1.12.
  63  */
  64
  65 #ifdef HAVE_CONFIG_H
  66 #include "config.h"
  67 #endif
  68
  69 #include "clutter-keyframe-transition.h"
  70
  71 #include "clutter-debug.h"
  72 #include "clutter-easing.h"
  73 #include "clutter-interval.h"
  74 #include "clutter-private.h"
  75 #include "clutter-timeline.h"
  76
  77 #include <math.h>
  78 #include <gobject/gvaluecollector.h>
  79
  80 typedef struct _KeyFrame
  81 {
  82   double key;
  83
  84   double start;
  85   double end;
  86
  87   ClutterAnimationMode mode;
  88
  89   ClutterInterval *interval;
  90 } KeyFrame;
  91
  92 struct _ClutterKeyframeTransitionPrivate
  93 {
  94   GArray *frames;
  95
  96   gint current_frame;
  97 };
  98
  99 G_DEFINE_TYPE (ClutterKeyframeTransition,
 100                clutter_keyframe_transition,
 101                CLUTTER_TYPE_PROPERTY_TRANSITION)
 102
 103 static void
 104 key_frame_free (gpointer data)
 105 {
 106   if (data != NULL)
 107     {
 108       KeyFrame *key = data;
 109
 110       g_object_unref (key->interval);
 111     }
 112 }
 113
 114 static int
 115 sort_by_key (gconstpointer a,
 116              gconstpointer b)
 117 {
 118   const KeyFrame *k_a = a;
 119   const KeyFrame *k_b = b;
 120
 121   if (fabs (k_a->key - k_b->key) < 0.0001)
 122     return 0;
 123
 124   if (k_a->key > k_a->key)
 125     return 1;
 126
 127   return -1;
 128 }
 129
 130 static inline void
 131 clutter_keyframe_transition_sort_frames (ClutterKeyframeTransition *transition)
 132 {
 133   if (transition->priv->frames != NULL)
 134     g_array_sort (transition->priv->frames, sort_by_key);
 135 }
 136
 137 static inline void
 138 clutter_keyframe_transition_init_frames (ClutterKeyframeTransition *transition,
 139                                          gssize                     n_key_frames)
 140 {
 141   ClutterKeyframeTransitionPrivate *priv = transition->priv;
 142   guint i;
 143
 144   priv->frames = g_array_sized_new (FALSE, FALSE,
 145                                     sizeof (KeyFrame),
 146                                     n_key_frames);
 147   g_array_set_clear_func (priv->frames, key_frame_free);
 148
 149   /* we add an implicit key frame that goes to 1.0, so that the
 150    * user doesn't have to do that an can simply add key frames
 151    * in between 0.0 and 1.0
 152    */
 153   for (i = 0; i < n_key_frames + 1; i++)
 154     {
 155       KeyFrame frame;
 156
 157       if (i == n_key_frames)
 158         frame.key = 1.0;
 159       else
 160         frame.key = 0.0;
 161
 162       frame.mode = CLUTTER_LINEAR;
 163       frame.interval = NULL;
 164
 165       g_array_insert_val (priv->frames, i, frame);
 166     }
 167 }
 168
 169 static inline void
 170 clutter_keyframe_transition_update_frames (ClutterKeyframeTransition *transition)
 171 {
 172   ClutterKeyframeTransitionPrivate *priv = transition->priv;
 173   guint i;
 174
 175   if (priv->frames == NULL)
 176     return;
 177
 178   for (i = 0; i < priv->frames->len; i++)
 179     {
 180       KeyFrame *cur_frame = &g_array_index (priv->frames, KeyFrame, i);
 181       KeyFrame *prev_frame;
 182
 183       if (i > 0)
 184         prev_frame = &g_array_index (priv->frames, KeyFrame, i - 1);
 185       else
 186         prev_frame = NULL;
 187
 188       if (prev_frame != NULL)
 189         {
 190           cur_frame->start = prev_frame->key;
 191
 192           if (prev_frame->interval != NULL)
 193             {
 194               const GValue *value;
 195
 196               value = clutter_interval_peek_final_value (prev_frame->interval);
 197
 198               if (cur_frame->interval != NULL)
 199                 clutter_interval_set_initial_value (cur_frame->interval, value);
 200               else
 201                 {
 202                   cur_frame->interval =
 203                     clutter_interval_new_with_values (G_VALUE_TYPE (value), value, NULL);
 204                 }
 205             }
 206         }
 207       else
 208         cur_frame->start = 0.0;
 209
 210       cur_frame->end = cur_frame->key;
 211     }
 212 }
 213
 214 static void
 215 clutter_keyframe_transition_compute_value (ClutterTransition *transition,
 216                                            ClutterAnimatable *animatable,
 217                                            ClutterInterval   *interval,
 218                                            gdouble            progress)
 219 {
 220   ClutterKeyframeTransition *self = CLUTTER_KEYFRAME_TRANSITION (transition);
 221   ClutterTimeline *timeline = CLUTTER_TIMELINE (transition);
 222   ClutterKeyframeTransitionPrivate *priv = self->priv;
 223   ClutterTransitionClass *parent_class;
 224   ClutterTimelineDirection direction;
 225   ClutterInterval *real_interval;
 226   gdouble real_progress;
 227   double t, d, p;
 228   KeyFrame *cur_frame = NULL;
 229
 230   real_interval = interval;
 231   real_progress = progress;
 232
 233   /* if we don't have any keyframe, we behave like our parent class */
 234   if (priv->frames == NULL)
 235     goto out;
 236
 237   direction = clutter_timeline_get_direction (timeline);
 238
 239   /* we need a normalized linear value */
 240   t = clutter_timeline_get_elapsed_time (timeline);
 241   d = clutter_timeline_get_duration (timeline);
 242   p = t / d;
 243
 244   if (priv->current_frame < 0)
 245     {
 246       if (direction == CLUTTER_TIMELINE_FORWARD)
 247         priv->current_frame = 0;
 248       else
 249         priv->current_frame = priv->frames->len - 1;
 250     }
 251
 252   cur_frame = &g_array_index (priv->frames, KeyFrame, priv->current_frame);
 253
 254   /* skip to the next key frame, depending on the direction of the timeline */
 255   if (direction == CLUTTER_TIMELINE_FORWARD)
 256     {
 257       if (p > cur_frame->end)
 258         {
 259           priv->current_frame = MIN (priv->current_frame + 1,
 260                                      priv->frames->len - 1);
 261
 262           cur_frame = &g_array_index (priv->frames, KeyFrame, priv->current_frame);
 263        }
 264     }
 265   else
 266     {
 267       if (p < cur_frame->start)
 268         {
 269           priv->current_frame = MAX (priv->current_frame - 1, 0);
 270
 271           cur_frame = &g_array_index (priv->frames, KeyFrame, priv->current_frame);
 272         }
 273     }
 274
 275   /* if we are at the boundaries of the transition, use the from and to
 276    * value from the transition
 277    */
 278   if (priv->current_frame == 0)
 279     {
 280       const GValue *value;
 281
 282       value = clutter_interval_peek_initial_value (interval);
 283       clutter_interval_set_initial_value (cur_frame->interval, value);
 284     }
 285   else if (priv->current_frame == priv->frames->len - 1)
 286     {
 287       const GValue *value;
 288
 289       cur_frame->mode = clutter_timeline_get_progress_mode (timeline);
 290
 291       value = clutter_interval_peek_final_value (interval);
 292       clutter_interval_set_final_value (cur_frame->interval, value);
 293     }
 294
 295   /* update the interval to be used to interpolate the property */
 296   real_interval = cur_frame->interval;
 297
 298   /* normalize the progress */
 299   real_progress = (p - cur_frame->start) / (cur_frame->end - cur_frame->start);
 300
 301 #ifdef CLUTTER_ENABLE_DEBUG
 302   if (CLUTTER_HAS_DEBUG (ANIMATION))
 303     {
 304       char *from, *to;
 305       const GValue *value;
 306
 307       value = clutter_interval_peek_initial_value (cur_frame->interval);
 308       from = g_strdup_value_contents (value);
 309
 310       value = clutter_interval_peek_final_value (cur_frame->interval);
 311       to = g_strdup_value_contents (value);
 312
 313       CLUTTER_NOTE (ANIMATION,
 314                     "cur_frame [%d] => { %g, %s, %s %s %s } - "
 315                     "progress: %g, sub-progress: %g\n",
 316                     priv->current_frame,
 317                     cur_frame->key,
 318                     clutter_get_easing_name_for_mode (cur_frame->mode),
 319                     from,
 320                     direction == CLUTTER_TIMELINE_FORWARD ? "->" : "<-",
 321                     to,
 322                     p, real_progress);
 323
 324       g_free (from);
 325       g_free (to);
 326     }
 327 #endif /* CLUTTER_ENABLE_DEBUG */
 328
 329 out:
 330   parent_class =
 331     CLUTTER_TRANSITION_CLASS (clutter_keyframe_transition_parent_class);
 332   parent_class->compute_value (transition, animatable, real_interval, real_progress);
 333 }
 334
 335 static void
 336 clutter_keyframe_transition_started (ClutterTimeline *timeline)
 337 {
 338   ClutterKeyframeTransition *transition;
 339
 340   transition = CLUTTER_KEYFRAME_TRANSITION (timeline);
 341
 342   transition->priv->current_frame = -1;
 343
 344   clutter_keyframe_transition_sort_frames (transition);
 345   clutter_keyframe_transition_update_frames (transition);
 346 }
 347
 348 static void
 349 clutter_keyframe_transition_completed (ClutterTimeline *timeline)
 350 {
 351   ClutterKeyframeTransitionPrivate *priv;
 352
 353   priv = CLUTTER_KEYFRAME_TRANSITION (timeline)->priv;
 354
 355   priv->current_frame = -1;
 356 }
 357
 358 static void
 359 clutter_keyframe_transition_finalize (GObject *gobject)
 360 {
 361   ClutterKeyframeTransitionPrivate *priv;
 362
 363   priv = CLUTTER_KEYFRAME_TRANSITION (gobject)->priv;
 364
 365   if (priv->frames != NULL)
 366     g_array_unref (priv->frames);
 367
 368   G_OBJECT_CLASS (clutter_keyframe_transition_parent_class)->finalize (gobject);
 369 }
 370
 371 static void
 372 clutter_keyframe_transition_class_init (ClutterKeyframeTransitionClass *klass)
 373 {
 374   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 375   ClutterTimelineClass *timeline_class = CLUTTER_TIMELINE_CLASS (klass);
 376   ClutterTransitionClass *transition_class = CLUTTER_TRANSITION_CLASS (klass);
 377
 378   g_type_class_add_private (klass, sizeof (ClutterKeyframeTransitionPrivate));
 379
 380   gobject_class->finalize = clutter_keyframe_transition_finalize;
 381
 382   timeline_class->started = clutter_keyframe_transition_started;
 383   timeline_class->completed = clutter_keyframe_transition_completed;
 384
 385   transition_class->compute_value = clutter_keyframe_transition_compute_value;
 386 }
 387
 388 static void
 389 clutter_keyframe_transition_init (ClutterKeyframeTransition *self)
 390 {
 391   self->priv =
 392     G_TYPE_INSTANCE_GET_PRIVATE (self, CLUTTER_TYPE_KEYFRAME_TRANSITION,
 393                                  ClutterKeyframeTransitionPrivate);
 394 }
 395
 396 /**
 397  * clutter_keyframe_transition_new:
 398  * @property_name: the property to animate
 399  *
 400  * Creates a new #ClutterKeyframeTransition for @property_name.
 401  *
 402  * Return value: (transfer full): the newly allocated
 403  *   #ClutterKeyframeTransition instance. Use g_object_unref() when
 404  *   done to free its resources.
 405  *
 406  * Since: 1.12
 407  */
 408 ClutterTransition *
 409 clutter_keyframe_transition_new (const char *property_name)
 410 {
 411   return g_object_new (CLUTTER_TYPE_KEYFRAME_TRANSITION,
 412                        "property-name", property_name,
 413                        NULL);
 414 }
 415
 416 /**
 417  * clutter_keyframe_transition_set_key_frames:
 418  * @transition: a #ClutterKeyframeTransition
 419  * @n_key_frames: the number of values
 420  * @key_frames: (array length=n_key_frames): an array of keys between 0.0
 421  *   and 1.0, one for each key frame
 422  *
 423  * Sets the keys for each key frame inside @transition.
 424  *
 425  * If @transition does not hold any key frame, @n_key_frames key frames
 426  * will be created; if @transition already has key frames, @key_frames must
 427  * have at least as many elements as the number of key frames.
 428  *
 429  * Since: 1.12
 430  */
 431 void
 432 clutter_keyframe_transition_set_key_frames (ClutterKeyframeTransition *transition,
 433                                             guint                      n_key_frames,
 434                                             const double              *key_frames)
 435 {
 436   ClutterKeyframeTransitionPrivate *priv;
 437   guint i;
 438
 439   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 440   g_return_if_fail (n_key_frames > 0);
 441   g_return_if_fail (key_frames != NULL);
 442
 443   priv = transition->priv;
 444
 445   if (priv->frames == NULL)
 446     clutter_keyframe_transition_init_frames (transition, n_key_frames);
 447   else
 448     g_return_if_fail (n_key_frames == priv->frames->len - 1);
 449
 450   for (i = 0; i < n_key_frames; i++)
 451     {
 452       KeyFrame *frame = &g_array_index (priv->frames, KeyFrame, i);
 453
 454       frame->key = key_frames[i];
 455     }
 456 }
 457
 458 /**
 459  * clutter_keyframe_transition_set_values:
 460  * @transition: a #ClutterKeyframeTransition
 461  * @n_values: the number of values
 462  * @values: (array length=n_values): an array of values, one for each
 463  *   key frame
 464  *
 465  * Sets the values for each key frame inside @transition.
 466  *
 467  * If @transition does not hold any key frame, @n_values key frames will
 468  * be created; if @transition already has key frames, @values must have
 469  * at least as many elements as the number of key frames.
 470  *
 471  * Since: 1.12
 472  */
 473 void
 474 clutter_keyframe_transition_set_values (ClutterKeyframeTransition *transition,
 475                                         guint                      n_values,
 476                                         const GValue              *values)
 477 {
 478   ClutterKeyframeTransitionPrivate *priv;
 479   guint i;
 480
 481   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 482   g_return_if_fail (n_values > 0);
 483   g_return_if_fail (values != NULL);
 484
 485   priv = transition->priv;
 486
 487   if (priv->frames == NULL)
 488     clutter_keyframe_transition_init_frames (transition, n_values);
 489   else
 490     g_return_if_fail (n_values == priv->frames->len - 1);
 491
 492   for (i = 0; i < n_values; i++)
 493     {
 494       KeyFrame *frame = &g_array_index (priv->frames, KeyFrame, i);
 495
 496       clutter_interval_set_final_value (frame->interval, &values[i]);
 497     }
 498 }
 499
 500 /**
 501  * clutter_keyframe_transition_set_modes:
 502  * @transition: a #ClutterKeyframeTransition
 503  * @n_modes: the number of easing modes
 504  * @modes: (array length=n_modes): an array of easing modes, one for
 505  *   each key frame
 506  *
 507  * Sets the easing modes for each key frame inside @transition.
 508  *
 509  * If @transition does not hold any key frame, @n_modes key frames will
 510  * be created; if @transition already has key frames, @modes must have
 511  * at least as many elements as the number of key frames.
 512  *
 513  * Since: 1.12
 514  */
 515 void
 516 clutter_keyframe_transition_set_modes (ClutterKeyframeTransition  *transition,
 517                                        guint                       n_modes,
 518                                        const ClutterAnimationMode *modes)
 519 {
 520   ClutterKeyframeTransitionPrivate *priv;
 521   guint i;
 522
 523   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 524   g_return_if_fail (n_modes > 0);
 525   g_return_if_fail (modes != NULL);
 526
 527   priv = transition->priv;
 528
 529   if (priv->frames == NULL)
 530     clutter_keyframe_transition_init_frames (transition, n_modes);
 531   else
 532     g_return_if_fail (n_modes == priv->frames->len - 1);
 533
 534   for (i = 0; i < n_modes; i++)
 535     {
 536       KeyFrame *frame = &g_array_index (priv->frames, KeyFrame, i);
 537
 538       frame->mode = modes[i];
 539     }
 540 }
 541
 542 /**
 543  * clutter_keyframe_transition_set: (skip)
 544  * @transition: a #ClutterKeyframeTransition
 545  * @gtype: the type of the values to use for the key frames
 546  * @n_key_frames: the number of key frames between the initial
 547  *   and final values
 548  * @...: a list of tuples, containing the key frame index, the value
 549  *   at the key frame, and the animation mode
 550  *
 551  * Sets the key frames of the @transition.
 552  *
 553  * This variadic arguments function is a convenience for C developers;
 554  * language bindings should use clutter_keyframe_transition_set_keys(),
 555  * clutter_keyframe_transition_set_modes(), and
 556  * clutter_keyframe_transition_set_values() instead.
 557  *
 558  * Since: 1.12
 559  */
 560 void
 561 clutter_keyframe_transition_set (ClutterKeyframeTransition *transition,
 562                                  GType                      gtype,
 563                                  guint                      n_key_frames,
 564                                  ...)
 565 {
 566   ClutterKeyframeTransitionPrivate *priv;
 567   va_list args;
 568   guint i;
 569
 570   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 571   g_return_if_fail (gtype != G_TYPE_INVALID);
 572   g_return_if_fail (n_key_frames > 0);
 573
 574   priv = transition->priv;
 575
 576   if (priv->frames == NULL)
 577     clutter_keyframe_transition_init_frames (transition, n_key_frames);
 578   else
 579     g_return_if_fail (n_key_frames == priv->frames->len - 1);
 580
 581   va_start (args, n_key_frames);
 582
 583   for (i = 0; i < n_key_frames; i++)
 584     {
 585       KeyFrame *frame = &g_array_index (priv->frames, KeyFrame, i);
 586       GValue value = G_VALUE_INIT;
 587       char *error = NULL;
 588
 589       frame->key = va_arg (args, double);
 590
 591       G_VALUE_COLLECT_INIT (&value, gtype, args, 0, &error);
 592       if (error != NULL)
 593         {
 594           g_warning ("%s: %s", G_STRLOC, error);
 595           g_free (error);
 596           break;
 597         }
 598
 599       frame->mode = va_arg (args, ClutterAnimationMode);
 600
 601       g_clear_object (&frame->interval);
 602       frame->interval = clutter_interval_new_with_values (gtype, NULL, &value);
 603
 604       g_value_unset (&value);
 605     }
 606
 607   va_end (args);
 608 }
 609
 610 /**
 611  * clutter_keyframe_transition_clear:
 612  * @transition: a #ClutterKeyframeTransition
 613  *
 614  * Removes all key frames from @transition.
 615  *
 616  * Since: 1.12
 617  */
 618 void
 619 clutter_keyframe_transition_clear (ClutterKeyframeTransition *transition)
 620 {
 621   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 622
 623   if (transition->priv->frames != NULL)
 624     {
 625       g_array_unref (transition->priv->frames);
 626       transition->priv->frames = NULL;
 627     }
 628 }
 629
 630 /**
 631  * clutter_keyframe_transition_get_n_key_frames:
 632  * @transition: a #ClutterKeyframeTransition
 633  *
 634  * Retrieves the number of key frames inside @transition.
 635  *
 636  * Return value: the number of key frames
 637  *
 638  * Since: 1.12
 639  */
 640 guint
 641 clutter_keyframe_transition_get_n_key_frames (ClutterKeyframeTransition *transition)
 642 {
 643   g_return_val_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition), 0);
 644
 645   if (transition->priv->frames == NULL)
 646     return 0;
 647
 648   return transition->priv->frames->len - 1;
 649 }
 650
 651 /**
 652  * clutter_keyframe_transition_set_key_frame:
 653  * @transition: a #ClutterKeyframeTransition
 654  * @index_: the index of the key frame
 655  * @key: the key of the key frame
 656  * @mode: the easing mode of the key frame
 657  * @value: a #GValue containing the value of the key frame
 658  *
 659  * Sets the details of the key frame at @index_ inside @transition.
 660  *
 661  * The @transition must already have a key frame at @index_, and @index_
 662  * must be smaller than the number of key frames inside @transition.
 663  *
 664  * Since: 1.12
 665  */
 666 void
 667 clutter_keyframe_transition_set_key_frame (ClutterKeyframeTransition *transition,
 668                                            guint                      index_,
 669                                            double                     key,
 670                                            ClutterAnimationMode       mode,
 671                                            const GValue              *value)
 672 {
 673   ClutterKeyframeTransitionPrivate *priv;
 674   KeyFrame *frame;
 675
 676   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 677
 678   priv = transition->priv;
 679   g_return_if_fail (priv->frames != NULL);
 680   g_return_if_fail (index_ < priv->frames->len - 1);
 681
 682   frame = &g_array_index (priv->frames, KeyFrame, index_);
 683   frame->key = key;
 684   frame->mode = mode;
 685   clutter_interval_set_final_value (frame->interval, value);
 686 }
 687
 688 /**
 689  * clutter_keyframe_transition_get_key_frame:
 690  * @transition: a #ClutterKeyframeTransition
 691  * @index_: the index of the key frame
 692  * @key: (out) (allow-none): return location for the key, or %NULL
 693  * @mode: (out) (allow-none): return location for the easing mode, or %NULL
 694  * @value: (out caller-allocates): a #GValue initialized with the type of
 695  *   the values
 696  *
 697  * Retrieves the details of the key frame at @index_ inside @transition.
 698  *
 699  * The @transition must already have key frames set, and @index_ must be
 700  * smaller than the number of key frames.
 701  *
 702  * Since: 1.12
 703  */
 704 void
 705 clutter_keyframe_transition_get_key_frame (ClutterKeyframeTransition *transition,
 706                                            guint                      index_,
 707                                            double                    *key,
 708                                            ClutterAnimationMode      *mode,
 709                                            GValue                    *value)
 710 {
 711   ClutterKeyframeTransitionPrivate *priv;
 712   const KeyFrame *frame;
 713
 714   g_return_if_fail (CLUTTER_IS_KEYFRAME_TRANSITION (transition));
 715
 716   priv = transition->priv;
 717   g_return_if_fail (priv->frames != NULL);
 718   g_return_if_fail (index_ < priv->frames->len - 1);
 719
 720   frame = &g_array_index (priv->frames, KeyFrame, index_);
 721
 722   if (key != NULL)
 723     *key = frame->key;
 724
 725   if (mode != NULL)
 726     *mode = frame->mode;
 727
 728   if (value != NULL)
 729     clutter_interval_get_final_value (frame->interval, value);
 730 }