Commit Graph

84 Commits

Author SHA1 Message Date
Emmanuele Bassi
ccd3b4c886 [animation] Simplify the Animation code
After long deliberation, the Animation class handling of the
:mode, :duration and :loop properties, as well as the conditions
for creating the Alpha and Timeline instances, came out as far too
complicated for their own good.

This is a rework of the API/parameters matrix and behaviour:

  - :mode accessors will create an Alpha, if needed
  - :duration and :loop accessors will create an Alpha and a Timeline
    if needed
  - :alpha will set or unset the Alpha
  - :timeline will set or unset the Timeline

Plus, more documentation on the Animation class itself.

Many thanks to Jonas Bonn <jonas@southpole.se> for the feedback
and the ideas.
2009-05-27 18:28:37 +01:00
Emmanuele Bassi
6fff1bcdc6 [animatable] Allow validation in ::animate_property
The Animatable interface implementation will always have the computed
value applied, whilst the non-Animatable objects go through the
interval validation first to avoid incurring in assertions and
warnings.

The Animatable::animate_property() should also be able to validate the
property it's supposed to interpolate, and eventually discard it. This
requires adding a return value to the virtual function (and its wrapper
function).

The Animation code will then apply the computed value only if the
animate_property() returns TRUE -- unifying the code path with the
non-Animatable objects.
2009-05-27 13:01:31 +01:00
Emmanuele Bassi
7edaf8ece8 [animation] Proxy properties whenever possible
The Animation class should proxy the :mode, :duration and :loop
properties whenever possible, to avoid them going out of sync when
changed using the Alpha and Timeline instances directly.

Currently, if Timeline:duration is changed, querying Animation:duration
will yield the old value, but the animation itself (being driven by
the Timeline) will use the Timeline's :duration new value. This holds
for the :loop and :mode properties as well.

Instead, the getters for the Animation's :duration, :loop and
:mode properties should ask the relevant object -- if any. The
loop, duration and mode values inside AnimationPrivate should only
be used if no Timeline or no Alpha instances are available, or
when creating new instances.
2009-05-27 12:12:11 +01:00
Emmanuele Bassi
1f44c3584c [animation] Defer the timeline handling to the Alpha
The Animation should not directly manipulate a Timeline instance,
but it should defer to the Alpha all handling of the timeline.

This means that:

  - set_duration() and set_loop() will either create a Timeline or
    will set the :duration and :loop properties on the Timeline; if
    the Timeline must be created, and no Alpha instance is available,
    then a new Alpha instance will be created as well and the newly
    create Timeline will be assigned to the Alpha

  - if set_mode() on an Animation instance without an Alpha, the
    Alpha will be created; a Timeline will also be created

  - set_alpha() will replace the Alpha; if the new Alpha does not
    have a Timeline associated then a Timeline will be created using
    the current :duration and :loop properties of Animation; otherwise,
    if the replaced Alpha had a timeline, the timeline will be
    transferred to the new one
2009-05-27 11:52:40 +01:00
Emmanuele Bassi
081813fd61 [animation] Do not leak timelines
The timeline created when calling set_timeline(NULL) is referenced
even though we implicitly own it. When the Animation is destroyed,
the timeline is then leaked.

Thanks to: Richard Heatley <richard.heatley@starleaf.com>

Fixes bug:

  http://bugzilla.openedhand.com/show_bug.cgi?id=1548
2009-05-07 19:25:24 +01:00
Emmanuele Bassi
ab1dcb8033 [animation] Remove InitiallyUnowned from Animation
ClutterAnimation currently inherits the initial floating reference
semantics from GInitiallyUnowned. An Animation is, though, meant to
be used as a top-level object, like a Timeline or a Behaviour, and
not "owned" by another object. For this reason, the initial floating
reference does not make any sense.
2009-05-06 17:01:44 +01:00
Emmanuele Bassi
d6d208da7d Remove Units from the public API
With the recent change to internal floating point values, ClutterUnit
has become a redundant type, defined to be a float. All integer entry
points are being internally converted to floating point values to be
passed to the GL pipeline with the least amount of conversion.

ClutterUnit is thus exposed as just a "pixel with fractionary bits",
and not -- as users might think -- as generic, resolution and device
independent units. not that it was the case, but a definitive amount
of people was convinced it did provide this "feature", and was flummoxed
about the mere existence of this type.

So, having ClutterUnit exposed in the public API doubles the entry
points and has the following disadvantages:

  - we have to maintain twice the amount of entry points in ClutterActor
  - we still do an integer-to-float implicit conversion
  - we introduce a weird impedance between pixels and "pixels with
    fractionary bits"
  - language bindings will have to choose what to bind, and resort
    to manually overriding the API
    + *except* for language bindings based on GObject-Introspection, as
      they cannot do manual overrides, thus will replicate the entire
      set of entry points

For these reason, we should coalesces every Actor entry point for
pixels and for ClutterUnit into a single entry point taking a float,
like:

  void clutter_actor_set_x (ClutterActor *self,
                            gfloat        x);
  void clutter_actor_get_size (ClutterActor *self,
                               gfloat       *width,
                               gfloat       *height);
  gfloat clutter_actor_get_height (ClutterActor *self);

etc.

The issues I have identified are:

  - we'll have a two cases of compiler warnings:
    - printf() format of the return values from %d to %f
    - clutter_actor_get_size() taking floats instead of unsigned ints
  - we'll have a problem with varargs when passing an integer instead
    of a floating point value, except on 64bit platforms where the
    size of a float is the same as the size of an int

To be clear: the *intent* of the API should not change -- we still use
pixels everywhere -- but:

  - we remove ambiguity in the API with regard to pixels and units
  - we remove entry points we get to maintain for the whole 1.0
    version of the API
  - we make things simpler to bind for both manual language bindings
    and automatic (gobject-introspection based) ones
  - we have the simplest API possible while still exposing the
    capabilities of the underlying GL implementation
2009-05-06 16:44:47 +01:00
Emmanuele Bassi
a1cc1f57ac [animation] Do not connect to ::completed multiple times
The clutter_actor_animate*() family of functions should only connect
to the Animation::completed signal once, during the construction of
the Animation object attached to the Actor. Otherwise, the completed
signal handler will be run multiple times, and will try to unref()
the Animation for each call -- leading to a segmentation fault.
2009-04-05 20:32:15 +01:00
Emmanuele Bassi
6bf883da6c [animation] Add the ::started signal
The Animation class is missing a ::started signal matching the
::completed one. A ::started signal is useful for debugging,
initial state set up, and checks.
2009-04-03 14:19:20 +01:00
Emmanuele Bassi
df738d0a8c [animation] Do not unref on ::complete by default
Bug 1535 - Complete animation always unrefs ClutterAnimation (even
           after g_object_ref_sink)

Animations created through clutter_animation_new() should not
automagically unref themselves by default on ::complete. We
only want that behaviour for Animations created by the
clutter_actor_animate* family of functions, since those provide
the automagic memory management.
2009-04-03 12:47:21 +01:00
Bastian Winkler
34467e5c6a [docs] Fix some inconsistency in Animation
For some examples of clutter_actor_animate the parameters of @mode and
@duration are swapped.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
2009-03-30 17:34:07 +01:00
Øyvind Kolås
f6d938a0db [animation] add varargs support for signal::completed
Added support for registering a handler for the completed signal
directly amongst the varargs making it easier to attach code
to be executed when animations complete.
2009-03-30 12:10:41 +01:00
Emmanuele Bassi
ccca24ab76 Remove usage of the grave accent as quotation mark
See:

  http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

This should make Thomas happy.
2009-03-17 14:13:31 +00:00
Emmanuele Bassi
567a96c96a [docs] More information on animation queueing
Queuing an animation on an actor cannot be done from within the
::completed signal handler, because we guarantee that the Animation
instance is valid and attached to the actor it animates for the
whole duration of the signal emission chain.

In order to queue animations you have to install an idle handler
on the main loop, and call clutter_actor_animate() inside it.

The documentation should be more clear about this caveat in the
memory management of ClutterAnimations created by the animate()
family of functions.
2009-03-16 18:20:58 +00:00
Emmanuele Bassi
216373047b [animation] Enhance consistency of the Animation API
The Animation API should follow this pattern:

  - functions with an Interval as part of the arguments should have
    "interval" inside their name, e.g.:

      clutter_animation_bind_interval
      clutter_animation_update_interval

  - functions dealing with property names should have "property"
    inside their name, e.g.:

      clutter_animation_has_property
      clutter_animation_unbind_property

    - unless -

  - functions dealing with a property and its value should not
    have any modifier, e.g.:

      clutter_animation_bind

The change from update_property() to update_interval() frees up
clutter_animation_update(), to be added at a later date.
2009-03-16 14:16:18 +00:00
Colin Walters
0cb0a841cc [animation] Enhance the bind API
Bug 1419 - Add clutter_animation_bind, rename clutter_animation_bind_interval

This is a different approach from the clutter_actor_animatev
vector variant.  The single call should be even easier on
automatic bindings, since calls can be chained like:

  new Clutter.Animation({object: myactor}).bind("x", 42).bind("y", 43);

Note clutter_animation_bind_property which took a ClutterInterval
is renamed to clutter_animation_bind_interval for clarity, and to
discourage use since there are friendlier APIs about.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
2009-03-16 12:13:55 +00:00
Emmanuele Bassi
156589fe3f [animation] Add Animation getter
If we are animating an actor using the clutter_actor_animate*() family
of functions we might want to expose a getter for the Animation instance
we are using, to avoid excessing bookkeeping.
2009-03-16 12:13:55 +00:00
Emmanuele Bassi
44d0733665 [animation] Add an emitter for ::completed
The ::completed signal requires an emitter in case we want to stop
the animation and safely dispose it inside application code without
breaking invariants.
2009-03-16 12:13:55 +00:00
Emmanuele Bassi
a5c88e62f2 [docs] Clarify Animation memory management
The memory management of the ClutterAnimation instances should be
heavily documented, given its "automagical" nature, so that other
people might understand it and avoid breaking it in the future.
2009-03-16 12:13:55 +00:00
Geoff Gustafson
2c95b378a5 [animation] Broken fixed:: properties
This commit yesterday:

89e3e3a4cc
[animation] Add vector variants for ::animate()

broke the "fixed::" attribute on properties in clutter_actor_animate(),
because the fixed:: part is still on the string when it checks to see if
it's a valid property the class knows about.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
2009-03-11 22:09:05 +00:00
Emmanuele Bassi
89e3e3a4cc [animation] Add vector variants for ::animate()
Bug 1438 - Implicit Animation API could use animatev variants

The clutter_actor_animate* family of functions use va_lists to
handle the property/value pairs for the final state of the
animation.

Language bindings have problems with variadic arguments functions,
and usually prefer vector-based API which allow a greater level
of control and conversion from native data types.

For each variadic arguments function in the clutter_actor_animate*
family there should be a vector-based version that takes:

  - the number of property/value pairs
  - a constant array of constant strings
  - an array of GValues

Most of the internal implementation can be refactored from the
current one, thus both the var_args and the vector entry points
share a common implementation of the code; then, both versions
of the API are just loops over a list of arguments.

Based on a patch by: Robert Carr <carrr@rpi.edu>
2009-03-10 12:38:04 +00:00
Emmanuele Bassi
c0adf4582c [docs] Clarify clutter_actor_animate() behaviour
When calling clutter_actor_animate() on an actor that is being
currently animated the default behaviour is to update the duration
of the animation; the easing mode; update all the common properties;
and finally add the new properties.

This:

  clutter_actor_animate (actor, 500, CLUTTER_LINEAR,
                         "width", 100,
                         "height", 100,
                         NULL);

  clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
                         "x", 100,
                         "y", 100,
                         "height", 200,
                         NULL);

Is logically equivalent to:

  clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
                         "x", 100,
                         "y", 100,
                         "width", 100,
                         "height", 200,
                         NULL);

The documentation of the function should be slightly more verbose
in describing the default behaviour.
2009-03-10 12:38:02 +00:00
Owen W. Taylor
c5afd98416 Add gobject-introspection annotations
Add annotations such as (transfer-none) (out) (element-type ClutterActor),
and so forth to the doc comments as appropriate.

The annotations added here are a combination of the annotations previously
in gir-repository for Clutter and annotations found in a review of all
return values with that were being parsed with a transfer of "full".

http://bugzilla.openedhand.com/show_bug.cgi?id=1452

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
2009-02-20 12:09:07 +00:00
Emmanuele Bassi
0c7e4172ab [animation] Do not bind construct-only properties
ClutterAnimation should not try to bind construct-only properties,
since it only manipulates existing instances.
2009-02-16 11:02:20 +00:00
Emmanuele Bassi
7d7372af43 [animation] Move the alpha value to floating point
The current Alpha value is an unsigned integer that can be used
implicitly as a fixed point value. This makes writing an alpha
function overshooting below and above the current range basically
impossible without complicating an already complex code, and
creating weird corner cases.

For this reason, the Alpha value should be defined as a floating
point normalized value, spanning a range between 0.0 and 1.0; in
order to allow overshooting, the valid range is extended one unit
below and one unit above, thus making it -1.0 .. 2.0.

This commit updates the various users of the ClutterAlpha API
and the tests cases.

This commit also removes all the current alpha functions exposed
in the public API.
2009-01-20 16:42:49 +00:00
Emmanuele Bassi
c096f41e70 [doc] Clarify the animation mode meaning
The animation mode parameters and properties are now slightly
anonymous unsigned longs, so we need to clarify in the documentation
that the user should either pass a ClutterAnimationMode value or
the result of registering an alpha function.
2009-01-16 14:37:42 +00:00
Emmanuele Bassi
d02819949d Remove AnimationMode from the Animation API
The animation mode symbolic id might come from the AnimationMode
enumeration or from the clutter_alpha_register_*() family of
functions. For this reason, we should use a gulong instead of
ClutterAnimationMode whenever we have an "animation mode" parameter
or property.
2009-01-16 14:37:42 +00:00
Emmanuele Bassi
db3d2e9568 Merge branch 'animatable-iface' into animation-improvements
* animatable-iface:
  [docs] Add ClutterAnimatable to the API reference
  Add license notice to ClutterAnimation files
  [animation] Use ClutterAnimatable inside Animation
  [animation] Add ClutterAnimatable
2009-01-08 13:38:51 +00:00
Emmanuele Bassi
068ba1caf0 [animation] Extend ClutterAnimation support to all objects
Instead of limiting the use of ClutterAnimation to ClutterActor
instances, relax the constraint to include all GObject classes.

ClutterAnimation is not using actor-specific API, since it is
only using properties.

The only actor-based API is the clutter_actor_animate() family
of functions.
2009-01-08 13:13:39 +00:00
Emmanuele Bassi
60cfa5edb2 [animation] Use ClutterAnimatable inside Animation
ClutterAnimation should check if the object is implementing the
Animatable interface, and if so delegate to it the computation
of the value along the interval initial and final value, depending
on the progress.
2009-01-08 12:59:16 +00:00
Emmanuele Bassi
ff48c3ef7c [animation] Interval::compute_value should return a boolean
If the computation of the interval value depending on the progress
was not successful, ClutterInterval::compute_value() should return
this information to the caller.
2009-01-07 18:18:59 +00:00
Neil Roberts
ff73fe3e1f Fix some animation_set_* functions so they cope if the value is the same
The following functions are fixed:

clutter_animation_set_actor
clutter_animation_set_timeline
clutter_animation_set_alpha

This is related to bug 1392 which discusses the problem for
behaviour_set_alpha.
2009-01-05 13:19:40 +00:00
Neil Roberts
62cfc6487f Fix setting the mode on a ClutterAlpha created with animation_set_alpha(NULL)
It previously attempted to set the mode on the alpha using
clutter_animation_set_mode_internal, but this was setting the mode on
priv->alpha. At that point in the code priv->alpha is always NULL.

clutter_animation_set_mode_internal now takes a parameter to specify
which alpha to modify.
2009-01-05 12:52:46 +00:00
Emmanuele Bassi
62844d5f04 2008-11-17 Emmanuele Bassi <ebassi@linux.intel.com>
Bug 1014 - Clutter Animation API Improvements

	* clutter/Makefile.am:
	* clutter/clutter.h: Update the build

	* clutter/clutter-types.h: Add AnimationMode, an enumeration
	for easing functions.

	* clutter/clutter-alpha.[ch]: Add the :mode property to
	control the function bound to an Alpha instance using an
	enumeration value. Also add six new alpha functions:

		- ease-in, ease-out, ease-in-out
		- sine-in, sine-out, sine-in-out

	* clutter/clutter-deprecated.h: Deprecate the #defines for
	the alpha functions. They will be replaced by entries in the
	ClutterAnimationMode.

	* clutter/clutter-interval.[ch]: Add ClutterInterval, an
	object for defining, validating and computing an interval
	between two values.

	* clutter/clutter-animation.[ch]: Add ClutterAnimation, an
	object responsible for animation the properties of a single
	actor along an interval of values. ClutterAnimation memory
	management is automatic. A simple wrapper method for
	ClutterActor is provided:

		clutter_actor_animate()

	which will create, or update, an animation for the passed
	actor.

	* clutter/clutter-debug.h:
	* clutter/clutter-main.c: Add a new 'animation' debug note.

	* clutter/clutter-script.c: Clean up the alpha functions
	whitelist, and add the new functions.

	* doc/reference/clutter/Makefile.am:
	* doc/reference/clutter/clutter-sections.txt: Update the
	API reference.

	* doc/reference/clutter/clutter-animation.xml: Renamed to
	doc/reference/clutter/clutter-animation-tutorial.xml to
	avoid clashes with the ClutterAnimation section.

	* doc/reference/clutter/clutter-docs.sgml: Renamed to
	doc/reference/clutter/clutter-docs.xml, as it was an XML
	file and not a SGML file.

	* tests/Makefile.am:
	* tests/interactive/Makefile.am:
	* tests/interactive/test-animation.c:
	* tests/interactive/test-easing.c: Add two tests for the
	new simple animation API and the easing functions.

	* tests/interactive/test-actors.c:
	* tests/interactive/test-behave.c:
	* tests/interactive/test-depth.c:
	* tests/interactive/test-effects.c:
	* tests/interactive/test-layout.c:
	* tests/interactive/test-multistage.c:
	* tests/interactive/test-paint-wrapper.c:
	* tests/interactive/test-rotate.c:
	* tests/interactive/test-scale.c:
	* tests/interactive/test-texture-quality.c:
	* tests/interactive/test-threads.c:
	* tests/interactive/test-viewport.c: Update interactive tests
	to the deprecations and new alpha API.
2008-11-18 09:50:03 +00:00