The interface looked like a good idea around the time Clutter 0.2 was
out, but in reality we never had a proper, and supported implementation
outside of clutter-gst - thus, ClutterMedia was acting like a wrapper
around GStreamer, leading to hilarious issues of impedence mismatch
between API and all sorts of indirection issues typical of wrong
abstractions.
In theory, ClutterMedia should have been deprecated and removed before
we hit 1.0, but we kept flip-flopping on the issue.
For 2.0, it's time to take it out.
And shoot it in the face.
This will make things interesting.
We have better replacements in ClutterActor, that do The Right Thing™
instead of deferring control and requiring reimplementation in every
single container actor.
ClutterBox functionality has been implemented by ClutterActor, and
proxied by the Box subclass; with the removal of the abstract bit on
ClutterActor, we can safely deprecated ClutterBox.
The clutter-stage.h header still has a bunch of macros that have, for
reasons unknown[*], survived the 1.0 API cut and have long since been
deprecated. Let's hide them under the deprecated/ carpet and let us
never speak of them ever again.
[*] pretty sure alcohol or other psychotropic substances were involved
but I take the 5th on that.
The code that has been deprecated should live into its own directory,
both in the repository and when installed. This should make it clear
which functionality is actually maintained and which is not.
We start with an oldie: the frame source API.
The clutter_actor_get_allocation_coords() is not used, and since
the switch to floats in the Actor's API, it returns exactly what
the get_allocation_box() returns.
The clutter_actor_pick() function just emits the ::pick signal
on the actor. Nobody should be using it, since the paint() method
is already context sensitive and will result in a ::pick emission
by itself. The clutter_actor_pick() is just confusing things.
The Vertex and ActorBox boxed types are meant to be used across
the API, but are fairly difficult to bind. Their memory management
is also unclear, and has to go through the indirection of
g_boxed_copy() and g_boxed_free().
The clutter_stage_fullscreen() and clutter_stage_unfullscreen() are
a GDK-ism. The underlying implementation is already using an accessor
with a boolean parameter.
This should take the amount of collisions between properties, methods
and signals to zero.
ClutterEvent is not really gobject-introspection friendly because
of the whole discriminated union thing. In particular, if you get
a ClutterEvent in a signal handler, you probably can't access the
event-type-specific fields, and you probably can't call methods
like clutter_key_event_symbol() either, because you can't cast the
ClutterEvent to a ClutterKeyEvent.
The cleanest solution is to turn every accessor into ClutterEvent
methods, accepting a ClutterEvent* and internally checking the event
type.
Fixes bug:
http://bugzilla.openedhand.com/show_bug.cgi?id=1585
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
Since we're planning to release 1.0 without any of the deprecated
API baggage, we can simply remove the set_uniform_1f() method from
ClutterShader public API and add it to the deprecated header.
The ClutterColor API has some inconsistencies:
- the string deserialization function does not match the rest of
the conversion function naming policy; the naming should be:
clutter_color_parse() -> clutter_color_from_string()
and the first parameter should be the ClutterColor that will
be set from the string, not the string itself (a GDK-ism).
- the fixed point API should not be exposed, especially in the
form of ClutterFixed values
- the non-fixed point HLS conversion functions do not make any
sense. The values returned should be:
hue := range [ 0, 360 ]
luminance := range [ 0, 1 ]
saturation := range [ 0, 1 ]
like the current fixed point API does. Returning a value in
the [ 0, 255 ] range is completely useless
- the clutter_color_equal() should be converted for its use inside
a GHashTable; a clutter_color_hash() should be added as well
- the second parameter of the clutter_color_shade() function should
be the shading factor, not the result (another GDK-ism). this way
the function call can be translated from this:
color.shade(out result, factor)
to the more natural:
color.shade(factor, out result)
This somewhat large commit fixes all these issues and updates the
internal users of the API.
The hope is that this function makes it easier to extend the font
settings with more flags without having to add a function for every
setting.
A new flag for enabling hinting has been added. If set, this changes
the font options on the global PangoContext and any newly created
PangoContexts. The options are only set if the flag is changed from
the default so it won't override any detailed setting chosen by the
backend.
The clutter_stage_get_resolution() and fixed-point API are just
shorthands for:
clutter_backend_get_resolution (default_backend);
And as such do not fit at all in the ClutterStage class. The only
reason for their existence was the ClutterUnit conversion macros,
which have now been fixed to use the default backend through a
function call instead.
Thus, we can safely remove the stage entry points.
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.
Bug #815 - Split up request, allocation, and paint box
* clutter/clutter-actor.[ch]: Rework the size allocation,
request and paint area. Now ::request_coords() is called
::allocate(), and ::query_coords() has been split into
::get_preferred_width() and ::get_preferred_height(). See
the documentation and the layout test on how to implement
a container and layout manager with the new API. (#915,
based on a patch by Havoc Pennington, Lucas Rocha and Johan
Bilien)
* clutter/clutter-clone-texture.c: Port CloneTexture to
the new size negotiation API; it just means forwarding
the requests to the parent texture.
* clutter/clutter-deprecated.h: Add deprecated and replaced
API.
* clutter/clutter-entry.c: Port Entry to the new size
negotiation API.
* clutter/clutter-group.c: Port Group to the new size
negotiation API; the semantics of the Group actor do not
change.
* clutter/clutter-label.c: Port Label to the new size
negotiation API, and vastly simplify the code.
* clutter/clutter-main.[ch]: Add API for executing a
relayout when needed.
* clutter/clutter-private.h: Add new Stage private API.
* clutter/clutter-rectangle.c: Update the get_abs_opacity()
call to get_paint_opacity().
* clutter/clutter-stage.c:
(clutter_stage_get_preferred_width),
(clutter_stage_get_preferred_height),
(clutter_stage_allocate),
(clutter_stage_class_init): Port Stage to the new size
negotiation API.
* clutter/clutter-texture.c: Port Texture to the new size
negotiation API.
* clutter/clutter-types.h: Add ClutterRequestMode enumeration.
* clutter/x11/clutter-stage-x11.c: Port the X11 stage
implementation to the new size negotiation API.
* tests/Makefile.am: Add the layout manager test case.
* tests/test-opacity.c: Update.
* tests/test-project.c: Update.
* tests/test-layout.c: Test case for a layout manager implemented
using the new size negotiation API; the layout manager handles
both transformed and untransformed children.
Bug #902 - Support transform from G_TYPE_INT to ClutterUnit
* clutter/clutter-units.c:
(clutter_value_transform_int_unit),
(clutter_unit_get_type): Add GValue transformation function from
integer values to ClutterUnit. (#902)
(param_unit_validate): Fix validation for ClutterParamSpecUnit;
this allows writable ClutterUnit properties.
* clutter/clutter-fixed.c:
(clutter_value_transform_int_fixed),
(clutter_value_transform_double_fixed),
(clutter_value_transform_float_fixed): Add GValue transformation
functions from native types (int, double, float) to ClutterFixed.
(clutter_fixed_get_type): Register the new transformation functions.
(param_fixed_validate): Fix validation for ClutterParamSpecUnit;
this allows writable ClutterFixed properties.
* README: Add a note about the Shader API changes.
* clutter/clutter-deprecated.h: Add deprecation symbols.
* clutter/clutter-shader.[ch]: Rename the :bound read-only
property to :compiled. Also rename clutter_shader_bind()
and clutter_shader_is_bound() to clutter_shader_compil() and
clutter_shader_is_compiled(), respectively.
* clutter/glx/clutter-stage-glx.c:
(clutter_stage_glx_unrealize): Update after
clutter_shader_release_all() rename.
* tests/test-shader.c (button_release_cb), (main): Update.
* clutter/clutter-feature.h:
* clutter/clutter-texture.c:
* clutter/clutter-texture.h:
* clutter/cogl/cogl.h:
* clutter/cogl/gl/cogl.c:
* clutter/cogl/gles/cogl.c:
* tests/Makefile.am:
* tests/test.fbo.c:
Add initial support for FBO's in Clutter (OpenGL only so far).
See new clutter_texture_new_from_actor()
Initial implementation, needs work.
* clutter/x11/clutter-stage-x11.c:
(clutter_stage_x11_set_cursor_visible):
Fall back to again not relying on xfixes to hide cursor. *sigh*
* clutter/clutter-deprecated.h:
Add clutter_group_find_child_by_id
* clutter/clutter-entry.h:
* clutter/clutter-entry.c:
(clutter_entry_set_cursor_position),
(clutter_entry_get_cursor_position): Rename [gs]et_position()
to [gs]set_cursor_position(), and avoid method name collisions
with bindings for high-level languages.
* clutter/clutter-deprecated.h: Add replacement warnings for the
renamed methods.
* clutter/NEWS:
Started 0.6.0 section with comment on actor anchor point.
* clutter/clutter/clutter-actor.c:
* clutter/clutter/clutter-actor.h:
* clutter/clutter/clutter-behaviour-scale.c:
* clutter/clutter/clutter-deprecated.h:
(clutter_actor_set_anchor_point):
(clutter_actor_set_anchor_pointu):
(clutter_actor_get_anchor_point):
(clutter_actor_get_anchor_pointu):
(clutter_actor_set_anchor_point_from_gravity):
New anchor point API deprecating old gravity scaling, added
comments on modelview matrix construction to ClutterActor
documentation.
(clutter_actor_set_scale_with_gravity):
(clutter_actor_set_scale_with_gravityx):
Deprecated; use clutter_actor_set_anchor_point_from_gravity() instead.
* clutter.symbols: Update exported symbols.
* clutter/clutter-actor.[ch]: Remove clutter_actor_rotate_*
and clutter_actor_get_rx* and provide a simpler rotation API:
clutter_actor_set_rotation() and clutter_actor_get_rotation().
* clutter/clutter-deprecated.h: Deprecate the old rotation API.
* clutter/clutter-behaviour-bspline.c:
* clutter/clutter-behaviour-rotate.c:
* clutter/clutter-effect.c: Update internal usage of the
rotation API.
* tests/test-project.c: Ditto as above.
* clutter/clutter-actor.[ch]: Rename clutter_actor_get_id() to
clutter_actor_get_gid().
(clutter_actor_set_parent): Use GUINT_TO_POINTER().
* clutter/clutter-deprecated.h: Add a replacement warning for
clutter_actor_get_id().
* clutter/clutter-texture.c (texture_upload_data): Use
clutter_actor_get_gid(), and don't leak the filename string.
