From f14837a6d1ceaa5dbf83f3de52b77919a07a71ee Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Fri, 15 Feb 2008 15:50:21 +0000 Subject: [PATCH] 2008-02-15 Emmanuele Bassi * clutter-animation.sgml: Fix the animations documentation. --- doc/reference/ChangeLog | 8 +- doc/reference/clutter-animation.sgml | 307 ++++++++++++++++++--------- 2 files changed, 208 insertions(+), 107 deletions(-) diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog index 6e3af5642..74f5cfe41 100644 --- a/doc/reference/ChangeLog +++ b/doc/reference/ChangeLog @@ -1,8 +1,10 @@ +2008-02-15 Emmanuele Bassi + + * clutter-animation.sgml: Fix the animations documentation. + 2008-02-15 Chris Lord - reviewed by: - - * clutter-docs.sgml: + * clutter-docs.sgml: Fix documentation. 2008-02-15 Matthew Allum diff --git a/doc/reference/clutter-animation.sgml b/doc/reference/clutter-animation.sgml index 453bbd8c2..d9ca878f0 100644 --- a/doc/reference/clutter-animation.sgml +++ b/doc/reference/clutter-animation.sgml @@ -87,89 +87,109 @@ rotate_actor (gpointer data)
Timelines - Clutter Timelines abstract a set period of time with a set rate at - which to call a provided call back function. + #ClutterTimelines abstract a set period of time with a set frame + rate at which to call a provided callback. + - They essentially extend g_timeout like functionality further by; + #ClutterTimelines also extend the timeout sources functionality + further by: + - Having a set duration (in milliseconds) and a set 'frame rate'. Essentially the rate at which the callback is called. - Passing current position information to the callback. - Handling 'dropped frames' in guarenteeing the set duration and skipping over frames if Clutter cannot keep up with set rates. - Query the number of milliseconds elapsed between current and previous callback. - Allowing the timeline to be modified on the fly as well as being stoped, started, looped, rewound, reversed. - Using the ClutterTimeoutPool to more efficiently schedule multiple timeout istances. + Having a set duration (in milliseconds) and a set + 'frame rate' - that is, the rate at which the callback is + called + Passing current progress information to the + callback + Handling 'dropped frames' and guarenteeing the set + duration by skipping over frames if the callback cannot keep up with + the set frame rate + Querying the number of milliseconds elapsed between + the current and previous callback. + Allowing the timeline to be modified on the fly as + well as being stopped, started, looped, rewound and + reversed + Using a #ClutterTimeoutPool to more efficiently + schedule multiple timeout sources without incurring in potential + starvation of the main loop slices + A Timeline is created with; + -clutter_timeline_new (guint n_frames, guint fps); +clutter_timeline_new (n_frames, frames_per_seconds); + Taking a number of frames and a frames per second, or by; + -clutter_timeline_new_for_duration (guint msecs); +clutter_timeline_new_for_duration (msecs); + - Which takes the duration of the timeline in milliseconds with a - default frame rate (See #clutter_get_default_frame_rate()) - + default frame rate (See clutter_get_default_frame_rate()). + The speed, duration and number of frames of the timeline then be modifed via the objects properties and API calls. The timeline can - be made to loop by settings it "loop" property to TRUE. + be made to loop by settings it "loop" property to %TRUE. - The timelines is started via #clutter_timeline_start () and its - playback further manipulated by the #clutter_timeline_pause (), - #clutter_timeline_stop (), #clutter_timeline_rewind () , - #clutter_timeline_skip () calls. + The timelines is started via clutter_timeline_start() and its + playback further manipulated by the clutter_timeline_pause(), + clutter_timeline_stop(), clutter_timeline_rewind() and + clutter_timeline_skip() calls. - By attaching a handler to the timelines "new-frame" signal a timeline - can then be used to drive an animation by altering actors visual - properties in this callback. The callback looks like; + By attaching a handler to the timeline's ClutterTimeline::new-frame + signal a timeline can then be used to drive an animation by altering + an actor's visual properties in this callback. The callback looks like: +void +on_new_frame (ClutterTimeline *timeline, + gint frame_num, + gpointer user_data) +{ - void on_new_frame (ClutterTimeline *timeline, - gint frame_num, - gpointer user_data) +} - The new-frame signals 'frame_num' parameter is set to the timelines - current frame number this is between 0 and the "num-frames" - property. This value can be used to compute the state of a - particular animation that is dependant on the current timeline - position. The function #clutter_timeline_get_progress () can also be - used to get a normalised value of the timelines current position. + The frame_num parameter is set to the timeline's + current frame number (which is between 0 and the "num-frames" property). + This value can be used to compute the state of a particular animation + that is dependant on the frame numer. The clutter_timeline_get_progress() + function can also be used to get a normalised value of the timeline's + current position between 0 and 1. - Timelines can also be played in reverse - #clutter_timeline_set_direction() and a one-time delay set before - they begin playing #clutter_timeline_set_delay (). + Timelines can also be played in reverse by setting the direction using + clutter_timeline_set_direction(), and can also have a one-time delay set + before they begin playing by using clutter_timeline_set_delay(). - When using a timeline to control a physical simulation using - #clutter_timeline_get_delta() allows retrieving the number of frames - and milliseconds since the previous callback to ensure the physics - simulation to be able to take the actual time elapsed between + Timelines can also control a pyshical simulation; the + clutter_timeline_get_delta() function allows retrieving the number of + frames and milliseconds elapsed since the previous callback to ensure + the physics engine to be able to take the actual time elapsed between iterations into account. @@ -188,9 +208,11 @@ on_new_frame (ClutterTimeline *timeline, { ClutterActor *actor = CLUTTER_ACTOR(data); - clutter_actor_set_rotation (actor, (gdouble)frame_num, - clutter_actor_get_width (actor)/2, - clutter_actor_get_height (actor)/2); + clutter_actor_set_rotation (actor, CLUTTER_Z_AXIS, + (gdouble) frame_num, + clutter_actor_get_width (actor) / 2, + clutter_actor_get_height (actor) / 2, + 0); } int @@ -213,8 +235,8 @@ main (int argc, char *argv[]) clutter_actor_set_position (actor, 100, 100); - timeline = clutter_timeline_new (360, 60); /* num frames, fps */ - g_object_set(timeline, "loop", TRUE, NULL); /* have it loop */ + timeline = clutter_timeline_new_for (360, 60); /* a degree per frame */ + clutter_timeline_set_loop (timeline, TRUE); g_signal_connect (timeline, "new-frame", G_CALLBACK (on_new_frame), actor); @@ -266,19 +288,58 @@ main (int argc, char *argv[]) - %CLUTTER_ALPHA_RAMP_INC - %CLUTTER_ALPHA_RAMP_DEC - %CLUTTER_ALPHA_RAMP - %CLUTTER_ALPHA_SINE - %CLUTTER_ALPHA_SINE_INC - %CLUTTER_ALPHA_SINE_DEC - %CLUTTER_ALPHA_SINE_HALF - %CLUTTER_ALPHA_SQUARE - %CLUTTER_ALPHA_SMOOTHSTEP_INC - %CLUTTER_ALPHA_SMOOTHSTEP_DEC - %CLUTTER_ALPHA_EXP_INC - %CLUTTER_ALPHA_EXP_DEC - + + + %CLUTTER_ALPHA_RAMP_INC + Increasing ramp function + + + %CLUTTER_ALPHA_RAMP_DEC + Decreasing ramp function + + + %CLUTTER_ALPHA_RAMP + Full ramp function + + + %CLUTTER_ALPHA_SINE_INC + Increasing sine function + + + %CLUTTER_ALPHA_SINE_DEC + Decreasing sine function + + + %CLUTTER_ALPHA_SINE_HALF + Half sine function + + + %CLUTTER_ALPHA_SINE + Full sine function + + + %CLUTTER_ALPHA_SQUARE + Square waveform ("step") function + + + %CLUTTER_ALPHA_SMOOTHSTEP_INC + Increasing smooth transition step + function + + + %CLUTTER_ALPHA_SMOOTHSTEP_DEC + Decreasing smooth transition step + function + + + %CLUTTER_ALPHA_EXP_INC + Increasing exponential function + + + %CLUTTER_ALPHA_EXP_DEC + Decreasing exponential function + + @@ -331,18 +392,42 @@ main (int argc, char *argv[]) - The behaviours included with clutter are + The behaviours included in Clutter are - #ClutterBehaviourBspline - #ClutterBehaviourDepth - #ClutterBehaviourEllipse - #ClutterBehaviourOpacity - #ClutterBehaviourPath - #ClutterBehaviourRotate - #ClutterBehaviourScale + + + #ClutterBehaviourBspline + Moves actors along a B-spline path + + + #ClutterBehaviourDepth + Changes the depth of actors + + + #ClutterBehaviourEllipse + Moves actors along an ellipsis + + + #ClutterBehaviourOpacity + Changes the opacity of actors + + + #ClutterBehaviourPath + Moves actors along a path + + + #ClutterBehaviourRotate + Rotates actors along an axis + + + #ClutterBehaviourScale + Changes the scaling factors of + actors + + @@ -372,22 +457,22 @@ main (int argc, char *argv[]) clutter_container_add_actor (CLUTTER_CONTAINER (stage), actor); - timeline = clutter_timeline_new (100, 26); /* num frames, fps */ - g_object_set(timeline, "loop", TRUE, NULL); /* have it loop */ + timeline = clutter_timeline_new_for_duration (4000); /* milliseconds */ + clutter_timeline_set_loop (timeline, TRUE); - /* Set an alpha func to power behaviour */ + /* Set an alpha func to power the behaviour */ alpha = clutter_alpha_new_full (timeline, CLUTTER_ALPHA_SINE, NULL, NULL); behave = clutter_behaviour_ellipse_new (alpha, - 200, /* center x */ - 200, /* center y */ - 400, /* width */ - 300, /* height */ + 200, /* center x */ + 200, /* center y */ + 400, /* width */ + 300, /* height */ CLUTTER_ROTATE_CW, /* direction */ - 0.0, /* angle begin */ - 360.0); /* angle end */ + 0.0, /* initial angle */ + 360.0); /* final angle */ clutter_behaviour_apply (behave, actor); @@ -397,6 +482,10 @@ main (int argc, char *argv[]) clutter_main(); + /* clean up */ + g_object_unref (behave); + g_object_unref (timeline); + return 0; } @@ -405,20 +494,22 @@ main (int argc, char *argv[]) Behaviour parameters can be changed whilst a animation is running - - There can be many ClutterAlpha's attached to a single timeline. There can be - many Behaviours for a ClutterAlpha There can be many Behaviours applied to an - actor. A ClutterScore can be used to chain many behaviour togeather + + There can be many #ClutterAlpha's attached to a single timeline. There + can be many behaviours for a #ClutterAlpha. There can be many behaviours + applied to an actor. A #ClutterScore can be used to chain many behaviour + together. -combining behaviours that effect the same actor properties -(i.e two seperate paths) will cause unexpected results. The values -will not be merged in any way with essentially a the last applied -behaviour taking precedence. + Combining behaviours that effect the same actor properties + (i.e two separate paths) will cause unexpected results. The values + will not be merged in any way with essentially a the last applied + behaviour taking precedence. - - FIXME: actually move subclassing behaviours here? - + + Tips for implementing a new behaviour can be found here. +
@@ -426,55 +517,60 @@ behaviour taking precedence. - ClutterEffect's provide a simplified abstraction for firing simple - transitions from code. ClutterEffects are created from - ClutterEffectTemplate s which are an abstraction of a timeline and - an alpha. An effect template can be created with: + Clutter effects API provide a simplified abstraction for firing simple + transitions from code. Clutter effects are created from a + #ClutterEffectTemplate which is an abstraction of a timeline and + an alpha function. An effect template can be created with: -ClutterEffectTemplate *etemplate; - -etemplate = clutter_effect_template_new_for_duration ( - 2000, CLUTTER_ALPHA_RAMP_INC); +ClutterEffectTemplate *etemplate = + clutter_effect_template_new_for_duration (2000, CLUTTER_ALPHA_RAMP_INC); This will create an effect template lasting 2000 milliseconds (2 - seconds) and use an alpha function of CLUTTER_ALPHA_RAMP_INC, there + seconds) and use an alpha function of %CLUTTER_ALPHA_RAMP_INC, there are other more advanced forms for creating effect templates from existing timelines, as well as attaching a callback to be called - with user_data when the effecttemplate is destroyed. + with user_data when the effect template is destroyed. - When we have an effect-template we can create a temporary behaviour + When we have an effect template we can create a temporary behaviour animating an actor simply by issuing: -clutter_actor_move (etemplate, actor, 23, 42, NULL, NULL); +clutter_effect_move (etemplate, actor, 23, 42, NULL, NULL); -and the actor will move to the coordintes 23, 42 in 2 seconds, if we at the -same time issued: +and the actor will move from its current position to the coordinates +(23, 42) in 2 seconds. Effects can also be stacked, so calling: -clutter_actor_fade (etemplate, actor, 0x0, NULL, NULL); +clutter_effect_move (etemplate, actor, 23, 42, NULL, NULL); +clutter_effect_fade (etemplate, actor, 0, NULL, NULL); -The actor would fade out at the same time. +The actor will move and fade out at the same time. - Clutter effects return a timeline, you can stop an effect from + Since effects return a #ClutterTimeline, you can stop an effect from immediatly happening by calling clutter_timeline_stop () on the - returned timeline. This returned timeline can also be used to then - use effects in the ClutterScore etc. + returned timeline. + + + + + The timeline and all the effect infrastructure is unreferenced as soon + as the timeline emits the ClutterTimeline::completed signal.
+
Conclusion @@ -493,7 +589,10 @@ The actor would fade out at the same time. - The animation functionality in clutter is primarily suited to building animations with a set or finite running time - i.e transitions and the like. For animations involving variable input (such as touchscreen handling) physical simulations may be more suited. + The animation functionality in Clutter is primarily suited to + building animations with a set or finite running time - i.e transitions + and the like. For animations involving variable input (such as touchscreen + handling) physical simulations may be more suited.