brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>

Browse Source 
* 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.
This commit is contained in:
Emmanuele Bassi 2008-02-15 11:27:34 +00:00
parent 37a923f0ee
commit 409cda1166
4 changed files with 151 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/reference/ChangeLog
View File

@ -1,3 +1,13 @@
2008-02-15 Emmanuele Bassi <ebassi@openedhand.com>
* 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 <ebassi@openedhand.com>
* clutter-docs.sgml: Fix varlistentry usage.

49
doc/reference/clutter-animation.sgml
View File

@ -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.
</para>
@ -28,9 +28,9 @@
<para>
The most basic way to create animations with Clutter is via the use of
the <code>g_timeout_add</code>. 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.
</para>
@ -39,23 +39,46 @@
Simple Rotation...
</para>
<programlisting>
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-&gt;actor, clos-&gt;current_angle, 0, 0, 0);
clos-&gt;current_angle += CFX_ONE;
if (clos-&gt;current_angle == clos-&gt;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,
&amp;clos);
</programlisting>
</example>
<note><title>Prioritys</title>
<note><title>Priorities</title>
<para>
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.
</para>
</note>
@ -214,7 +237,7 @@ main (int argc, char *argv[])
</section>
<section id="clutter-animation-behaviours">
<title>Timelines</title>
<title>Behaviours</title>
<para>
With a large application containing many animations, the use of just

19
doc/reference/creating-your-own-behaviours.sgml
View File

@ -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.
</para>
<example id="clutter-actor-query-coords-example">
<para>This example demonstrates a behaviour that produces a vertical 'wipe' like affect by modifying the actors clip region</para>
<para>This example demonstrates a behaviour that produces a vertical
'wipe' like affect by modifying the actors clip region</para>
<programlisting>
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&lt;n; i++)
for (i = 0; i&lt;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);
}
}
}
</programlisting>
</example>

109
doc/reference/subclassing-ClutterActor.sgml
View File

@ -13,19 +13,6 @@
<title>Implementing a new actor</title>
<programlisting>
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 ?
</programlisting>
<para>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)
</programlisting>
</example>
<para>When painting a blended actor, cogl_enable() should be called with
the %CGL_BLEND flag; or, alternatively, glEnable() with %GL_BLEND on
OpenGL.</para>
<para>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,
</programlisting>
</example>
<para></para>
<section id="implementing-clutter-container">
<title>Implementing Containers</title>
<para>
The #ClutterContainer interface should be implemented by subclasses
of #ClutterActor who wants to provide a general API for adding child
actors.
</para>
<para>
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():
</para>
<example id="clutter-actor-set-parent-example">
<programlisting>
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-&gt;baz)
clutter_actor_unparent (foo_actor-&gt;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);
}
</programlisting>
</example>
<para>
In order to implement the #ClutterContainer interface, these virtual
functions must be defined:
<variablelist>
<varlistentry>
<term>ClutterContainer::add</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ClutterContainer::remove</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ClutterContainer::foreach</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ClutterContainer::raise</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ClutterContainer::lower</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>ClutterContainer::sort_depth_order</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
</chapter>