diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog index d8698cbfc..cbc1a36aa 100644 --- a/doc/reference/ChangeLog +++ b/doc/reference/ChangeLog @@ -1,3 +1,13 @@ +2008-02-15 Emmanuele Bassi + + * clutter-animation.sgml: Fix some of the grammar; add a timeout-based + animation example. + + * creating-your-own-behaviours.sgml: Fix some of the linking. + + * subclassing-ClutterActor.sgml: Remove the FIXMEs; add the initial + structure of a section about containers. + 2008-02-15 Emmanuele Bassi * clutter-docs.sgml: Fix varlistentry usage. diff --git a/doc/reference/clutter-animation.sgml b/doc/reference/clutter-animation.sgml index 82e4fc35e..453bbd8c2 100644 --- a/doc/reference/clutter-animation.sgml +++ b/doc/reference/clutter-animation.sgml @@ -17,7 +17,7 @@ With Clutter using hardware accelration for graphics rendering, complex and fast animations are possible. This chapter describes basic - techniques and the utilitys Clutter provides in aiding animation + techniques and the utilities Clutter provides in aiding animation creation. @@ -28,9 +28,9 @@ The most basic way to create animations with Clutter is via the use of - the g_timeout_add. This enables a callback function to be - called at a definefine interval. The callback function can then modify - actors visual properties as to produce an animation. + g_timeout_add(). This enables a callback function to be called at a + defined interval. The callback function can then modify actors visual + properties as to produce an animation. @@ -39,23 +39,46 @@ Simple Rotation... +struct RotationClosure { + ClutterActor *actor; + ClutterFixed final_angle; + ClutterFixed current_angle; +}; - FIXME +static gboolean +rotate_actor (gpointer data) +{ + RotationClosure *clos = data; - guint g_timeout_add (guint interval, - GSourceFunc function, - gpointer data); + clutter_actor_set_rotationx (clos->actor, clos->current_angle, 0, 0, 0); + clos->current_angle += CFX_ONE; + if (clos->current_angle == clos->final_angle) + return FALSE; + + return TRUE; +} + +... + RotationClosure clos = { NULL, } + + clos.actor = an_actor; + clos.final_angle = CLUTTER_FLOAT_TO_FIXED (360.0); + clos.current_angle = 0; + + g_timeout_add (1000 / 360, /* fps to interval in milliseconds */ + rotate_actor, + &clos); - Prioritys + Priorities - G_PRIORITY_DEFAULT should always be used as the timeouts priority - (in case of g_timeout_add_full) as not to intefere with Clutters - schueduling of repaints and input event handling. + %G_PRIORITY_DEFAULT should always be used as the timeouts priority + (in case of g_timeout_add_full()) as not to intefere with Clutter's + scheduling of repaints and input event handling. @@ -214,7 +237,7 @@ main (int argc, char *argv[])
- Timelines + Behaviours With a large application containing many animations, the use of just diff --git a/doc/reference/creating-your-own-behaviours.sgml b/doc/reference/creating-your-own-behaviours.sgml index 27b18d0de..85ab95ca0 100644 --- a/doc/reference/creating-your-own-behaviours.sgml +++ b/doc/reference/creating-your-own-behaviours.sgml @@ -27,46 +27,47 @@ In order to implement a new #ClutterBehaviour subclass the usual machinery for subclassing a GObject should be used. The new subclass then just overides the ClutterBehaviour::alpha_notify() method. This - method is passed an alpha_value which is then used to computer + method is passed an alpha value which is then used to compute modifications to any actors the behaviour is applied to. - This example demonstrates a behaviour that produces a vertical 'wipe' like affect by modifying the actors clip region + This example demonstrates a behaviour that produces a vertical + 'wipe' like affect by modifying the actors clip region static void clutter_behaviour_foo_alpha_notify (ClutterBehaviour *behaviour, guint32 alpha_value) { - ClutterActor *actor - gint i, n; - gdouble factor; + ClutterActor *actor + gint i, n; + gdouble factor; /* Normalise alpha value */ - factor = (gdouble)alpha_value / CLUTTER_ALPHA_MAX_ALPHA; + factor = (gdouble) alpha_value / CLUTTER_ALPHA_MAX_ALPHA; n = clutter_behaviour_get_n_actors (behaviour); /* Change clip height of each applied actor. Note usually better to use * clutter_behaviour_actors_foreach () for performance reasons. */ - for (i=0; i<n; i++) + for (i = 0; i<n; i++) { int clip_height; actor = clutter_behaviour_get_nth_actor (behaviour, i); clip_height = clutter_actor_get_height (actor) - - (clutter_actor_get_height (actor) * factor); + - (clutter_actor_get_height (actor) * factor); clutter_actor_set_clip (actor, 0, 0, clutter_actor_get_width (actor), clip_height); - } + } } diff --git a/doc/reference/subclassing-ClutterActor.sgml b/doc/reference/subclassing-ClutterActor.sgml index 3b3723500..68ab96d42 100644 --- a/doc/reference/subclassing-ClutterActor.sgml +++ b/doc/reference/subclassing-ClutterActor.sgml @@ -13,19 +13,6 @@ Implementing a new actor - - A few FIXMES: - - more on composite/container actors, when/why to use... - + implementaing a composite actor - set_parent() etc - + implementing a container - interface etc - - Painting - + note on cogl_enable if painting texture or blended item - (should at least call cogl_enable(0) - to reset state cache) - + fine to use regular GL but then wont be portable - + avoid further transforms ? - - - In order to implement a new #ClutterActor subclass the usual machinery for subclassing a GObject should be used. After that, the ClutterActor::query_coords() and ClutterActor::request_coords() virtual @@ -138,6 +125,10 @@ foo_actor_paint (ClutterActor *actor) + When painting a blended actor, cogl_enable() should be called with + the %CGL_BLEND flag; or, alternatively, glEnable() with %GL_BLEND on + OpenGL. + If the actor has a non-rectangular shape, or it has internal childrens that needs to be distinguished by the events delivery mechanism, the ClutterActor::pick() method should also be overridden. The ::pick() method @@ -184,6 +175,96 @@ foo_actor_pick (ClutterActor *actor, - +
+ Implementing Containers + + + The #ClutterContainer interface should be implemented by subclasses + of #ClutterActor who wants to provide a general API for adding child + actors. + + + + If the #ClutterActor subclass only handles internal children, or it's + not suitable for having generic actors added to it, it should not + implement the #ClutterContainer interface, but simply use + clutter_actor_set_parent(): + + + + +void +foo_actor_add_baz (FooActor *foo_actor, + BazActor *baz_actor) +{ + g_return_if_fail (FOO_IS_ACTOR (foo_actor)); + g_return_if_fail (BAZ_IS_ACTOR (baz_actor)); + + /* unparent the previous BazActor; this will automatically call + * g_object_unref() on the actor + */ + if (foo_actor->baz) + clutter_actor_unparent (foo_actor->baz); + + foo_actor->baz = baz_actor; + + /* this will cause the initial floating reference to disappear, + * and add a new reference on baz_actor. foo_actor has now taken + * ownership of baz_actor + */ + clutter_actor_set_parent (CLUTTER_ACTOR (baz_actor), + CLUTTER_ACTOR (foo_actor)); + + g_signal_emit (foo_actor, foo_actor_signals[BAZ_CHANGED], 0, baz_actor); +} + + + + + In order to implement the #ClutterContainer interface, these virtual + functions must be defined: + + + + ClutterContainer::add + + + + + + ClutterContainer::remove + + + + + + ClutterContainer::foreach + + + + + + ClutterContainer::raise + + + + + + ClutterContainer::lower + + + + + + ClutterContainer::sort_depth_order + + + + + + + + +