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
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.
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.
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.
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.
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.
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.
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>
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.
The ::completed signal requires an emitter in case we want to stop
the animation and safely dispose it inside application code without
breaking invariants.
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.
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>
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>
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.
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>
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.
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.
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.
* animatable-iface:
[docs] Add ClutterAnimatable to the API reference
Add license notice to ClutterAnimation files
[animation] Use ClutterAnimatable inside Animation
[animation] Add ClutterAnimatable
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.
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.
If the computation of the interval value depending on the progress
was not successful, ClutterInterval::compute_value() should return
this information to the caller.
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.
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.
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.
