isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2025-06-14 01:09:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merged clutter-ivan branch into trunk.

Browse Source 
svn merge \
 https://svn.o-hand.com/repos/clutter/trunk/clutter@2509 \
 https://svn.o-hand.com/repos/clutter/branches/clutter-ivan@HEAD
This commit is contained in:
Neil Roberts
2008-04-25 13:37:36 +00:00
parent 7c3cf35eec
commit 6409b1adeb
123 changed files with 20528 additions and 3377 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
doc/reference/clutter/Makefile.am Normal file
View File

@ -0,0 +1,129 @@
## Process this file with automake to produce Makefile.in
# We require automake 1.6 at least.
AUTOMAKE_OPTIONS = 1.6
# This is a blank Makefile.am for using gtk-doc.
# Copy this to your project's API docs directory and modify the variables to
# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
# of using the various options.
# The name of the module, e.g. 'glib'.
DOC_MODULE=clutter
# The top-level SGML file. You can change this if you want to.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code. Relative to $(srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=../../../clutter
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=--type-init-func="clutter_base_init()"
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS=--deprecated-guards="CLUTTER_DISABLE_DEPRECATED"
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS=\
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gobject \
--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
--extra-dir=$(PANGO_PREFIX)/share/gtk-doc/html/pango \
--extra-dir=$(GDPIXBUF_PREFIX)/share/gtk-doc/html/gdk-pixbuf
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(top_srcdir)/clutter/*.h \
$(top_srcdir)/clutter/x11/clutter-x11.h \
$(top_srcdir)/clutter/win32/clutter-win32.h
CFILE_GLOB=$(top_srcdir)/clutter/*.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES=\
clutter.h \
clutter-debug.h \
clutter-deprecated.h \
clutter-enum-types.h \
clutter-json.h \
clutter-keysyms.h \
clutter-keysyms-table.h \
clutter-marshal.h \
clutter-model-private.h \
clutter-private.h \
clutter-id-pool.h \
clutter-script-private.h \
stamp-clutter-enum-types.h \
stamp-clutter-marshal.h \
cogl \
eglnative \
eglx \
glx \
osx \
x11 \
json \
pango \
sdl \
win32
EXTRA_HFILES=\
../../../clutter/x11/clutter-x11.h \
../../../clutter/win32/clutter-win32.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES=\
actor-box.png \
alpha-func.png \
event-flow.png \
path-alpha-func.png
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files= \
subclassing-ClutterActor.sgml \
clutter-animation.sgml \
creating-your-own-behaviours.sgml \
version.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files= \
subclassing-ClutterActor.sgml \
clutter-animation.sgml \
creating-your-own-behaviours.sgml
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
INCLUDES=-I$(top_srcdir) -I$(top_srcdir)/clutter $(CLUTTER_CFLAGS)
GTKDOC_LIBS=$(top_builddir)/clutter/libclutter-@CLUTTER_FLAVOUR@-@CLUTTER_MAJORMINOR@.la $(CLUTTER_LIBS)
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
EXTRA_DIST = \
version.xml.in \
actor-box.png \
alpha-func.png \
event-flow.png \
path-alpha-func.png

BIN
doc/reference/clutter/actor-box.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
doc/reference/clutter/alpha-func.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

600
doc/reference/clutter/clutter-animation.sgml Normal file
View File

@ -0,0 +1,600 @@
<chapter id="clutter-animations">
<chapterinfo>
<author>
<firstname>Matthew</firstname>
<surname>Allum</surname>
<affiliation>
<address>
<email>mallum@openedhand.com</email>
</address>
</affiliation>
</author>
</chapterinfo>
<title>Creating Animations with Clutter</title>
<para>
With Clutter using hardware accelration for graphics rendering,
complex and fast animations are possible. This chapter describes basic
techniques and the utilities Clutter provides in aiding animation
creation.
</para>
<section id="clutter-animation-basic">
<title>Basic Animations</title>
<para>
The most basic way to create animations with Clutter is via the use of
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>
<example id="clutter-timeout-example">
<para>
Simple Rotation...
</para>
<programlisting>
struct RotationClosure {
ClutterActor *actor;
ClutterFixed final_angle;
ClutterFixed current_angle;
};
static gboolean
rotate_actor (gpointer data)
{
RotationClosure *clos = 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>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 Clutter's
scheduling of repaints and input event handling.
</para>
</note>
</section>
<section id="clutter-animation-timelines">
<title>Timelines</title>
<para>
#ClutterTimeline<!-- -->s abstract a set period of time with a set frame
rate at which to call a provided callback.
</para>
<para>
#ClutterTimeline<!-- -->s also extend the timeout sources functionality
further by:
</para>
<orderedlist>
<listitem><para>Having a set duration (in milliseconds) and a set
'frame rate' - that is, the rate at which the callback is
called</para></listitem>
<listitem><para>Passing current progress information to the
callback</para></listitem>
<listitem><para>Handling 'dropped frames' and guarenteeing the set
duration by skipping over frames if the callback cannot keep up with
the set frame rate</para></listitem>
<listitem><para>Querying the number of milliseconds elapsed between
the current and previous callback.</para></listitem>
<listitem><para>Allowing the timeline to be modified on the fly as
well as being stopped, started, looped, rewound and
reversed</para></listitem>
<listitem><para>Using a #ClutterTimeoutPool to more efficiently
schedule multiple timeout sources without incurring in potential
starvation of the main loop slices</para></listitem>
</orderedlist>
<para>
A Timeline is created with;
</para>
<programlisting>
clutter_timeline_new (n_frames, frames_per_seconds);
</programlisting>
<para>
Taking a number of frames and a frames per second, or by;
</para>
<programlisting>
clutter_timeline_new_for_duration (msecs);
</programlisting>
<para>
Which takes the duration of the timeline in milliseconds with a
default frame rate (See clutter_get_default_frame_rate()).
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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:
</para>
<programlisting>
void
on_new_frame (ClutterTimeline *timeline,
gint frame_num,
gpointer user_data)
{
}
</programlisting>
<para>
The <literal>frame_num</literal> 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.
</para>
<para>
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().
</para>
<para>
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.
</para>
<example id="clutter-timeline-example">
<para>
The following example demonstrates rotating an actor with a timeline.
</para>
<programlisting>
#include &lt;clutter/clutter.h&gt;
void
on_new_frame (ClutterTimeline *timeline,
gint frame_num,
gpointer data)
{
ClutterActor *actor = CLUTTER_ACTOR(data);
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
main (int argc, char *argv[])
{
ClutterTimeline *timeline;
ClutterActor *stage, *actor;
GdkPixbuf *pixbuf;
clutter_init (&amp;argc, &amp;argv);
stage = clutter_stage_get_default ();
pixbuf = gdk_pixbuf_new_from_file ("an-image.png", NULL);
actor = clutter_texture_new_from_pixbuf (pixbuf);
clutter_container_add_actor (CLUTTER_CONTAINER (stage), actor);
clutter_actor_set_position (actor, 100, 100);
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);
clutter_actor_show_all (stage);
clutter_timeline_start (timeline);
clutter_main();
return 0;
}
</programlisting>
</example>
<note><para>
Multiple timelines can be sequenced in order by means of the
#ClutterScore. See the #ClutterScore documentation for more details on
using this.
</para></note>
</section>
<section id="clutter-animation-behaviours">
<title>Behaviours</title>
<para>
With a large application containing many animations, the use of just
timelines can become unweldy and difficult to manage with much code
duplication in the new-frame handlers that can require over complex
code changes for minor animation modifications. To ease these
problems the #ClutterAlpha and #ClutterBehaviour classes were created.
</para>
<para>
#ClutterAlpha and #ClutterBehaviour attempt to generalise the
new-frame function by defining common actions or behaviours that can
be quickly modified, applied to multiple actors or mixed on a single
actor.
</para>
<para>
A ClutterAlpha is simply a 'function of time' (not pixel alpha!). It
is created by referencing a source timeline and a function which
produces a value between 0 and %CLUTTER_ALPHA_MAX dependant on the
timeline position. Various prebuilt alpha functions are included
with Clutter these include
</para>
<para>
<variablelist>
<varlistentry>
<term>%CLUTTER_ALPHA_RAMP_INC</term>
<listitem><simpara>Increasing ramp function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_RAMP_DEC</term>
<listitem><simpara>Decreasing ramp function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_RAMP</term>
<listitem><simpara>Full ramp function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SINE_INC</term>
<listitem><simpara>Increasing sine function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SINE_DEC</term>
<listitem><simpara>Decreasing sine function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SINE_HALF</term>
<listitem><simpara>Half sine function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SINE</term>
<listitem><simpara>Full sine function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SQUARE</term>
<listitem><simpara>Square waveform ("step") function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SMOOTHSTEP_INC</term>
<listitem><simpara>Increasing smooth transition step
function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_SMOOTHSTEP_DEC</term>
<listitem><simpara>Decreasing smooth transition step
function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_EXP_INC</term>
<listitem><simpara>Increasing exponential function</simpara></listitem>
</varlistentry>
<varlistentry>
<term>%CLUTTER_ALPHA_EXP_DEC</term>
<listitem><simpara>Decreasing exponential function</simpara></listitem>
</varlistentry>
</variablelist>
</para>
<para>
A Behaviour is created with a #ClutterAlpha and a set of limits for
whatever the behaviour modifys actor wise. The current #ClutterAlpha
value is then mapped to a value between these limits and this value
set on any applied actors. With the #ClutterAlpha's underlying
timeline playing the produced value will change and the behaviour
will animate the actor.
</para>
<para>
A #ClutterBehaviour is effectively 'driven' by a supplied #ClutterAlpha and
when then applied to an actor it will modify a visual property or
feature of the actor dependant on the Alpha's value. For example a
path based behaviour applied to an actor will alter its position
along the path dependant on the current alpha value over time. The
actual motion will depend on the chosen #ClutterAlphaFunc - a
#CLUTTER_ALPHA_RAMP_INC making it to move at constant speed along the
path, a #CLUTTER_ALPHA_SINE making it alternate from one end of the
path to the other with non constant speed.
</para>
<para>
Multiple behaviours can of course be applied to an actor as well as
a single behaviour being applied to multiple actors. The separation
of timelines, alphas and behaviours allows for a single timeline to
drive many behaviours each potentially using different alpha
functions. Behaviour parameters can also be changed on the fly.
</para>
<para>
<figure id="behaviour-path-alpha">
<title>Effects of alpha functions on a path</title>
<graphic fileref="path-alpha-func.png" format="PNG"/>
<blockquote>
The actors position between the path's end points directly correlates
to the #ClutterAlpha's current alpha value driving the behaviour. With
the #ClutterAlpha's function set to %CLUTTER_ALPHA_RAMP_INC the actor
will follow the path at a constant velocity, but when changing to
%CLUTTER_ALPHA_SINE_INC the actor initially accelerates before quickly
decelerating.
</blockquote>
</figure>
</para>
<para>
The behaviours included in Clutter are
</para>
<para>
<variablelist>
<varlistentry>
<term>#ClutterBehaviourBspline</term>
<listitem><simpara>Moves actors along a B-spline path</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourDepth</term>
<listitem><simpara>Changes the depth of actors</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourEllipse</term>
<listitem><simpara>Moves actors along an ellipsis</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourOpacity</term>
<listitem><simpara>Changes the opacity of actors</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourPath</term>
<listitem><simpara>Moves actors along a path</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourRotate</term>
<listitem><simpara>Rotates actors along an axis</simpara></listitem>
</varlistentry>
<varlistentry>
<term>#ClutterBehaviourScale</term>
<listitem><simpara>Changes the scaling factors of
actors</simpara></listitem>
</varlistentry>
</variablelist>
</para>
<example id="clutter-timeline-example">
<para>
The following example demonstrates an ellipse behaviour in action.
</para>
<programlisting>
#include &lt;clutter/clutter.h&gt;
int
main (int argc, char *argv[])
{
ClutterTimeline *timeline;
ClutterBehaviour *behave;
ClutterAlpha *alpha;
ClutterActor *stage, *actor;
GdkPixbuf *pixbuf;
clutter_init (&amp;argc, &amp;argv);
stage = clutter_stage_get_default ();
pixbuf = gdk_pixbuf_new_from_file ("ohpowers.png", NULL);
actor = clutter_texture_new_from_pixbuf (pixbuf);
clutter_container_add_actor (CLUTTER_CONTAINER (stage), actor);
timeline = clutter_timeline_new_for_duration (4000); /* milliseconds */
clutter_timeline_set_loop (timeline, TRUE);
/* 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 */
CLUTTER_ROTATE_CW, /* direction */
0.0, /* initial angle */
360.0); /* final angle */
clutter_behaviour_apply (behave, actor);
clutter_actor_show_all (stage);
clutter_timeline_start (timeline);
clutter_main();
/* clean up */
g_object_unref (behave);
g_object_unref (timeline);
return 0;
}
</programlisting>
</example>
<note>Behaviour parameters can be changed whilst a animation is running</note>
<para>
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.
</para>
<warning><para>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.</para></warning>
<para>
Tips for implementing a new behaviour can be found <link
linkend="creating-your-own-behaviours">here</link>.
</para>
</section>
<section id="clutter-animation-effects">
<title>Effects</title>
<para>
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:
</para>
<programlisting>
ClutterEffectTemplate *etemplate =
clutter_effect_template_new_for_duration (2000, CLUTTER_ALPHA_RAMP_INC);
</programlisting>
<para>
This will create an effect template lasting 2000 milliseconds (2
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 effect template is destroyed.
</para>
<para>
When we have an effect template we can create a temporary behaviour
animating an actor simply by issuing:
</para>
<programlisting>
clutter_effect_move (etemplate, actor, 23, 42, NULL, NULL);
</programlisting>
<para>
and the actor will move from its current position to the coordinates
(23, 42) in 2 seconds. Effects can also be stacked, so calling:
</para>
<programlisting>
clutter_effect_move (etemplate, actor, 23, 42, NULL, NULL);
clutter_effect_fade (etemplate, actor, 0, NULL, NULL);
</programlisting>
<para>
The actor will move and fade out at the same time.
</para>
<para>
Since effects return a #ClutterTimeline, you can stop an effect from
immediatly happening by calling clutter_timeline_stop () on the
returned timeline.
</para>
<para>
The timeline and all the effect infrastructure is unreferenced as soon
as the timeline emits the ClutterTimeline::completed signal.
</para>
</section>
<section id="clutter-animation-conclusion">
<title>Conclusion</title>
<para>
Clutter provides a number of utility classes to aid animations and
complex animations can be produced by combining the various features
provided.
</para>
<para>
Of course animations can be created outside of Clutter Utilities,
they are not expected to cover every kind of possible animation
scenario.
</para>
<para>
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.
</para>
</section>
</chapter>

495
doc/reference/clutter/clutter-docs.sgml Normal file
View File

@ -0,0 +1,495 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
<!ENTITY clutter-SubclassingActor SYSTEM "xml/subclassing-ClutterActor.sgml">
<!ENTITY clutter-animation SYSTEM "xml/clutter-animation.sgml">
<!ENTITY creating-your-own-behaviours SYSTEM "xml/creating-your-own-behaviours.sgml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Clutter &version; Reference Manual</title>
<releaseinfo>Version &version;</releaseinfo>
<copyright>
<year>2008</year>
<holder>OpenedHand LTD</holder>
</copyright>
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the <citetitle>GNU Free
Documentation License</citetitle>, Version 1.1 or any later
version published by the Free Software Foundation with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. You may obtain a copy of the <citetitle>GNU Free
Documentation License</citetitle> from the Free Software
Foundation by visiting <ulink type="http"
url="http://www.fsf.org">their Web site</ulink> or by writing
to:
<address>
The Free Software Foundation, Inc.,
<street>59 Temple Place</street> - Suite 330,
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
<country>USA</country>
</address>
</para>
</legalnotice>
</bookinfo>
<part id="clutter">
<title>Clutter Overview</title>
<partintro>
<para>
Clutter is a GObject based library for creating fast, visually
rich, graphical user interfaces.
</para>
<para>
Clutter works by manipulating a scene-graph of 2D surfaces, or 'actors',
inside a 3D space.
</para>
<para>
#ClutterActor is the base class for such surfaces. All
#ClutterActor<!-- -->s can be positioned, scaled and rotated in 3D space.
In addition, other properties can be set, such as 2D clipping, children and
opacity. Tranforms applied to a parent actor also apply to any children.
Actors are also able to receive events.
</para>
<para>
Subclasses of #ClutterActor include #ClutterStage, #ClutterTexture,
#ClutterLabel, #ClutterRectangle, #ClutterEntry and
#ClutterGroup. #ClutterActor<!-- -->s are added to a parent, transformed
and then made visible.
</para>
<para>
#ClutterStage is the top level #ClutterActor - it's the representation
of a window, or framebuffer. It is created automatically when Clutter is
initialised. #ClutterStage is a #ClutterGroup, a class
implementing the #ClutterCointainer interface. Clutter currently
only supports a single stage.
</para>
<para>
#ClutterTimeline<!-- -->s provide the basis for Clutter's animation
utilities. Multiple timelines can be synchronised using #ClutterScore,
and #ClutterBehaviour and #ClutterEffect allow for the creation of
animation effects such as transitions.
</para>
<para>
Clutter further contains a number of utilities, including;
#ClutterScript - for loading 'UI definition' files formatted in
JSON, #ClutterShader - a class for applying GPU shaders to actors,
#ClutterModel - a utility class for MVC list type implementations
and #ClutterFixed - fixed point math utilities.
</para>
</partintro>
</part>
<part id="clutterbuilding">
<title>Building Clutter</title>
<partintro>
<section id='dependencies'>
<title>Clutter Dependencies</title>
<variablelist>
<varlistentry>
<term>GLib</term>
<listitem>
<para>A general-purpose utility library, not specific to
graphical user interfaces. GLib provides many useful data
types, macros, type conversions, string utilities, file
utilities, a main loop abstraction, and so on.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GObject</term>
<listitem>
<para>The GLib Object System provides the required
implementations of a flexible, extensible and intentionally
easy to map (into other languages) object-oriented framework
for C.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Pango</term>
<listitem>
<para>Pango is a library for laying out and rendering
text, with an emphasis on internationalization.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GDK-Pixbuf</term>
<listitem>
<para>GDK-Pixbuf is a library for loading and manipulating
various image file formats.</para>
</listitem>
<term>Backend Windowing System Library</term>
<listitem>
<para>GLX, EGL (1.1), SDL, Cocoa (OS X) and WGL (Windows)</para>
</listitem>
<term>Graphics Rendering </term>
<listitem>
<para>Open GL (1.2+) ir Open GL ES (1.1) </para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id='building-instructions'>
<title>Platform-specific instructions</title>
<section id='building-linux'>
<title>Linux</title>
<para>If you are using Debian or Ubuntu, you can install pre-compiled
binary packages the normal Debian way following the instructions at
<ulink type="http" url="http://debian.o-hand.com/">
http://debian.o-hand.com/</ulink>.
</para>
<para>To build Clutter clutter from sources, get the latest source
archives from <ulink type="http"
url="http://www.clutter-project.org/sources/">
http://www.clutter-project.org/sources/</ulink>. Once you have extracted
the sources from the archive execute the following commands in the
top-level directory:
</para>
<literallayout>
./configure
make
make install
</literallayout>
<para>You can configure the build with number of additional arguments
passed to the configure script, the full list of which can be obtained
by running ./configure --help. The following arguments are specific to
Clutter:
<variablelist>
<varlistentry>
<term>--enable-debug=[no/minimum/yes]</term>
<listitem>
<para>Turns on debugging. Possible values are: yes - all
glib asserts, checks and runtime clutter verbose messages;
minimum - just glib cast checks and runtime clutter verbose
messagaes; no - no glib asserts or checks and no runtime
clutter verbose messages; default=yes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-maintainer-flags=[no/yes]</term>
<listitem>
<para>Use strict compiler flags; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-gtk-doc</term>
<listitem>
<para>Use gtk-doc to build documentation; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-manual=[no/yes]</term>
<listitem>
<para>Build application developers manual; requires jw and
xmlto binaries; default=no.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-flavour=[glx/eglx/eglnative/sdl]</term>
<listitem>
<para>Select the Clutter backend; default=glx.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section id='building-windows'>
<title>Windows</title>
<para>
The recommended way of building Clutter for Windows is using the
<ulink type="http" url="http://www.mingw.org/">mingw</ulink> tool
chain. One option is to cross-compile Clutter under Linux -- you
can use the script found in the <filename>build/mingw/</filename>
directory to simplify the process (the script takes care of setting
up the necessary dependencies).
</para>
<para>
If you wish to build Clutter using mingw direcly under Windows, you
can do so the normal *nix way (described above) using the mingw
POSIX shell. Should you prefer to use Microsoft Visual Studio, a
project file for MSVC 2005 is located in the
<filename>build/msvc_2k5/</filename> directory. In either case, you
will need to first install the required dependencies.
</para>
<para>
There are currently two backends that are supported on
Windows. One uses the Win32 and WGL APIs directly and the
other is built on top of SDL. You must choose one of the
backends when running the configure script using the
following argument:
<variablelist>
<varlistentry>
<term>--with-flavour=[win32/sdl]</term>
<listitem>
<para>Select the Clutter backend; default=glx.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section id='building-osx'>
<title>OSX</title>
<para>The recommended way of building Clutter on OSX is to use
<ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>,
following the documentation for building the GTK+ stack as shown
<ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.
</para>
<para>
Jhbuild depends on SVN, which can be installed on OSX by using
the <ulink href="http://www.macports.org/">MacPorts</ulink>
project.
</para>
<para>
XCode should also be installed, either from the OSX installation
disk or downloading it from the Apple website.
</para>
<para>
Due to Clutter's dependency on GDK-Pixbuf, GTK+ for OSX must
also be built. After building GTK+, extract the files from
Clutter's release tar archive or check out the project from
SVN. Clutter OSX backend is built by passing the
<literal>--with-flavour=osx</literal> command line argument
to the configure script.
</para>
<para>
GTK-Doc is not working on OSX, so API reference generation
should also be disabled when building Clutter, by using
the <literal>--disable-docs</literal> and
<literal>--disable-gtk-doc</literal> command line argument
to the configure script.
</para>
</section>
</section>
</partintro>
</part>
<part id="clutterbase">
<title>Clutter Core Reference</title>
<chapter>
<title>Abstract classes and interfaces</title>
<xi:include href="xml/clutter-actor.xml"/>
<xi:include href="xml/clutter-container.xml"/>
<xi:include href="xml/clutter-media.xml"/>
</chapter>
<chapter>
<title>Base actors</title>
<xi:include href="xml/clutter-rectangle.xml"/>
<xi:include href="xml/clutter-texture.xml"/>
<xi:include href="xml/clutter-clone-texture.xml"/>
<xi:include href="xml/clutter-label.xml"/>
<xi:include href="xml/clutter-entry.xml"/>
</chapter>
<chapter>
<title>Container actors</title>
<xi:include href="xml/clutter-group.xml"/>
<xi:include href="xml/clutter-stage.xml"/>
</chapter>
</part>
<part id="clutteranimation">
<title>Clutter Animation Support</title>
<chapter>
<title>Base classes</title>
<xi:include href="xml/clutter-timeline.xml"/>
<xi:include href="xml/clutter-score.xml"/>
<xi:include href="xml/clutter-alpha.xml"/>
<xi:include href="xml/clutter-behaviour.xml"/>
</chapter>
<chapter>
<title>Behaviours</title>
<xi:include href="xml/clutter-behaviour-bspline.xml"/>
<xi:include href="xml/clutter-behaviour-depth.xml"/>
<xi:include href="xml/clutter-behaviour-ellipse.xml"/>
<xi:include href="xml/clutter-behaviour-opacity.xml"/>
<xi:include href="xml/clutter-behaviour-path.xml"/>
<xi:include href="xml/clutter-behaviour-rotate.xml"/>
<xi:include href="xml/clutter-behaviour-scale.xml"/>
</chapter>
<chapter>
<title>Simple effects API</title>
<xi:include href="xml/clutter-effect.xml"/>
</chapter>
</part>
<part>
<title>Clutter Tools</title>
<chapter>
<title>General purpose API</title>
<xi:include href="xml/clutter-color.xml"/>
<xi:include href="xml/clutter-event.xml"/>
<xi:include href="xml/clutter-fixed.xml"/>
<xi:include href="xml/clutter-main.xml"/>
<xi:include href="xml/clutter-shader.xml"/>
<xi:include href="xml/clutter-units.xml"/>
<xi:include href="xml/clutter-util.xml"/>
<xi:include href="xml/clutter-version.xml"/>
</chapter>
<chapter>
<title>User interface definition</title>
<xi:include href="xml/clutter-script.xml"/>
<xi:include href="xml/clutter-scriptable.xml"/>
</chapter>
<chapter>
<title>Generic list model</title>
<xi:include href="xml/clutter-model.xml"/>
<xi:include href="xml/clutter-model-iter.xml"/>
<xi:include href="xml/clutter-list-model.xml"/>
</chapter>
</part>
<part>
<title>Clutter Backends</title>
<partintro>
<para>Clutter is usually compiled against a specific drawing backend.
All backends have a common API for querying the underlying platform,
and some of them might have specific API exposed by Clutter.</para>
</partintro>
<xi:include href="xml/clutter-backend.xml"/>
<xi:include href="xml/clutter-x11.xml"/>
<xi:include href="xml/clutter-win32.xml"/>
</part>
<part>
<title>Additional Documentation</title>
<partintro>
<para>This section contains additional useful documentation for
developing with Clutter.</para>
</partintro>
&clutter-SubclassingActor;
&clutter-animation;
&creating-your-own-behaviours;
</part>
<index>
<title>Index</title>
</index>
<index role="deprecated">
<title>Index of deprecated symbols</title>
</index>
<index role="0.2">
<title>Index of new symbols in 0.2</title>
</index>
<index role="0.4">
<title>Index of new symbols in 0.4</title>
</index>
<index role="0.6">
<title>Index of new symbols in 0.6</title>
</index>
<appendix id="license">
<title>License</title>
<para>
This library is free software; you can redistribute it and/or
modify it under the terms of the <citetitle>GNU Library General
Public License</citetitle> as published by the Free Software
Foundation; either version 2 of the License, or (at your option)
any later version.
</para>
<para>
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
<citetitle>GNU Library General Public License</citetitle> for
more details.
</para>
<para>
You may obtain a copy of the <citetitle>GNU Library General
Public License</citetitle> from the Free Software Foundation by
visiting <ulink type="http" url="http://www.fsf.org">their Web
site</ulink> or by writing to:
<address>
Free Software Foundation, Inc.
<street>59 Temple Place</street> - Suite 330
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
<country>USA</country>
</address>
</para>
</appendix>
</book>

1350
doc/reference/clutter/clutter-sections.txt Normal file
View File

File diff suppressed because it is too large Load Diff

29
doc/reference/clutter/clutter.types Normal file
View File

@ -0,0 +1,29 @@
#include <clutter/clutter.h>
clutter_actor_get_type
clutter_group_get_type
clutter_stage_get_type
clutter_rectangle_get_type
clutter_texture_get_type
clutter_clone_texture_get_type
clutter_label_get_type
clutter_timeline_get_type
clutter_media_get_type
clutter_behaviour_get_type
clutter_alpha_get_type
clutter_behaviour_bspline_get_type
clutter_behaviour_depth_get_type
clutter_behaviour_ellipse_get_type
clutter_behaviour_opacity_get_type
clutter_behaviour_path_get_type
clutter_behaviour_rotate_get_type
clutter_behaviour_scale_get_type
clutter_backend_get_type
clutter_entry_get_type
clutter_script_get_type
clutter_scriptable_get_type
clutter_model_get_type
clutter_model_iter_get_type
clutter_list_model_get_type
clutter_score_get_type
clutter_shader_get_type

81
doc/reference/clutter/creating-your-own-behaviours.sgml Normal file
View File

@ -0,0 +1,81 @@
<chapter id="creating-your-own-behaviours">
<chapterinfo>
<author>
<firstname>Matthew</firstname>
<surname>Allum</surname>
<affiliation>
<address>
<email>mallum@openedhand.com</email>
</address>
</affiliation>
</author>
</chapterinfo>
<title>Creating You Own Behaviours</title>
<para>
Clutter comes with a number of fairly generic prebuilt behaviour
classes which provide a basis for transitions, animations and other
visual effects. However even with the ability to combine a number of
these behaviours sometimes they are not enough and a custom
behaviour is needed to create a spcific animation.
</para>
<para>
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 compute
modifications to any actors the behaviour is applied to.
</para>
<example id="clutter-behaviour-alpha-notify-example">
<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;
/* Normalise alpha value */
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++)
{
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_set_clip (actor,
0,
0,
clutter_actor_get_width (actor),
clip_height);
}
}
</programlisting>
</example>
<para>
If the new behaviour is meant to set an initial state on the
actors to which its applied to, then the ClutterBehaviour::applied
signal class handler should be overridden.
</para>
</chapter>

BIN
doc/reference/clutter/event-flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
doc/reference/clutter/path-alpha-func.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

270
doc/reference/clutter/subclassing-ClutterActor.sgml Normal file
View File

@ -0,0 +1,270 @@
<chapter id="clutter-subclassing-ClutterActor">
<chapterinfo>
<author>
<firstname>Emmanuele</firstname>
<surname>Bassi</surname>
<affiliation>
<address>
<email>ebassi@openedhand.com</email>
</address>
</affiliation>
</author>
</chapterinfo>
<title>Implementing a new actor</title>
<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
functions should be overidden. Optionally, also the ClutterActor::paint()
virtual functions should be overridden.</para>
<para>The ClutterActor::query_coords() method of a #ClutterActor is
invoked when clutter_actor_query_coords() is called on an instance
of that actor class. It is used to return a #ClutterActorBox containing
the coordinates of the bounding box for the actor (the coordinates
of the top left corner and of the bottom right corner of the rectangle
that fully contains the actor). Container actors, or composite actors
with internal children, should call clutter_actor_query_coords() on
each visible child. Remember: the returned coordinates must be relative
to the parent actor.</para>
<note>All the coordinates are expressed using #ClutterUnit<!-- -->s,
the internal high-precision unit type, which guarantee sub-pixel
precision. #ClutterUnit has the same limitation that #ClutterFixed
has, see the <link linkend="clutter-Fixed-Point-Support">fixed point page</link>.</note>
<example id="clutter-actor-query-coords-example">
<para>This example shows how an actor class should override the
query_coords() virtual function of #ClutterActor. In this case,
the returned bounding box is the sum of the bounding boxes of all
the <structname>FooActor</structname> children.</para>
<programlisting>
static void
foo_actor_query_coords (ClutterActor *actor,
ClutterActorBox *box)
{
FooActor *foo_actor = FOO_ACTOR (actor);
GList *child;
/* Clutter uses high-precision units which can be converted from
* and into pixels, typographic points, percentages, etc.
*/
ClutterUnit width, height;
/* initialize our size */
width = height = 0;
for (l = foo_actor-&gt;children; l != NULL; l = l-&gt;next)
{
ClutterActor *child_actor = child-&gt;data;
/* we consider only visible actors */
if (CLUTTER_ACTOR_IS_VISIBLE (child_actor))
{
ClutterActorBox child_box = { 0, };
clutter_actor_query_coords (child_actor, &amp;child_box);
width += child_box.x2 - child_box.x2;
height += child_box.y2 - child_box.y1;
}
}
box-&gt;x2 = box-&gt;x1 + width
box-&gt;y2 = box-&gt;y1 + height;
}
</programlisting>
</example>
<para>The ClutterActor::request_coords() method of a #ClutterActor
is invoked when clutter_actor_request_coords() is called on an instance
of that actor class. It is used to set the coordinates of the bounding
box for the actor. Container actors, or composite actors with internal
children, should override the request_coords() virtual function and call
clutter_actor_request_coords() on each visible child. Every actor class
overriding the request_coords() virtual function must chain up to the
parent class request_coords() method.</para>
<para>The ClutterActor::paint() method should be overridden if the
actor needs to control its drawing process, by using the GL API
directly. Actors performing transformations should push the GL matrix
first and then pop the GL matrix before returning. Container actors
or composite actors with internal children should do the same, and call
clutter_actor_paint() on every visible child:</para>
<para>When inside the ClutterActor::paint() method the actor is already
positioned at the coordinates specified by its bounding box; all the
paint operations should then take place from the (0, 0) coordinates.</para>
<example id="clutter-actor-paint-example">
<programlisting>
static void
foo_actor_paint (ClutterActor *actor)
{
FooActor *foo_actor = FOO_ACTOR (actor);
GList *child;
/* by including &lt;clutter/cogl.h&gt; it's possible to use the internal
* COGL abstraction API, which is also used by Clutter itself and avoids
* changing the GL calls depending on the target platform (GL or GL/ES).
*/
cogl_push_matrix ();
for (child = foo_actor-&gt;children; child != NULL; child = child-&gt;next)
{
ClutterActor *child_actor = child-&gt;data;
if (CLUTTER_ACTOR_IS_MAPPED (child_actor))
clutter_actor_paint (child_actor);
}
cogl_pop_matrix ();
}
</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
works exactly like the ::paint() method, but the actor should paint just
its shape with the passed colour:</para>
<example id="clutter-actor-pick-example">
<programlisting>
static void
foo_actor_pick (ClutterActor *actor,
const ClutterColor *pick_color)
{
FooActor *foo_actor = FOO_ACTOR (actor);
guint width, height;
/* it is possible to avoid a costly paint by checking whether the
* actor should really be painted in pick mode
*/
if (!clutter_actor_should_pick_paint (actor))
return;
/* by including &lt;clutter/cogl.h&gt; it's possible to use the internal
* COGL abstraction API, which is also used by Clutter itself and avoids
* changing the GL calls depending on the target platform (GL or GL/ES).
*/
cogl_color (pick_color);
clutter_actor_get_size (actor, &amp;width, &amp;height);
/* it is also possible to use raw GL calls, at the cost of losing
* portability
*/
glEnable (GL_BLEND);
/* draw a triangular shape */
glBegin (GL_POLYGON);
glVertex2i (width / 2, 0 );
glVertex2i (width , height);
glVertex2i (0 , height);
glEnd ();
cogl_pop_matrix ();
}
</programlisting>
</example>
<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>

1
doc/reference/clutter/version.xml.in Normal file
View File

@ -0,0 +1 @@
@CLUTTER_MAJORMINOR@