[clutter] Clutter backend rework landed in /trunk

hi everyone;

yesterday there has been a somewhat massive change in clutter /trunk, as
I committed the backend rework code; this led to a bunch of API changes
from the stable clutter-0-2 branch, so it'll probably affect developers
using clutter when the current trunk is released as version 0.4.

this mail should explain a bit what happened, what changed and hopefully
explain why.

+++

up until now, clutter used to mix GLX and pure GL calls inside the stage
and the main context initialisation process; in order to add support for
other backends, we had to isolate and move the GLX specific code into
its own separate source files. thus we created a ClutterBackend abstract
class, holding backend-specific data; a ClutterBackend plugs into the
initialisation process (it can check for environment variables and add
command line options and switches which will be parsed by
clutter_init()) and provides a backend-specific main stage. the
ClutterStage class was changed to reflect this, by becoming an abstract
class. Clutter backends must implement a ClutterBackend and a
ClutterStage classes, which will be available for the developer to use.
the GLX backend should show how a backend for clutter should be
implemented.

since different backends may also have different ways of getting the
events, each backend has now to provide its own event queue. in the
previous releases, clutter has processed the events from X directly as
they arrived in the X event queue; this was suboptimal, and we meant to
change it as soon as we overhauled the backend system. now, each backend
should implement a queue where events are pushed and popped out; this
allowed the ClutterStage actor to receive more events, like the scroll
event or the double/triple clicks, but also exposes an API to put, get
and peek events into and from the queue; it'll also allow running custom
event filters for the brave souls wanting to play with that.

what changed in the public API?

+ Additions:
  clutter_glx_trap_x_errors()
  clutter_glx_untrap_x_errors()
  clutter_glx_get_default_display()
  clutter_glx_get_default_screen()
  clutter_glx_get_root_window()
  clutter_glx_get_stage_window()
  clutter_glx_get_stage_visual()
  clutter_glx_set_stage_foreign()
        -- you have to explicitly include the clutter-glx.h header
           to get these functions, as these are specific to the
           GLX backend (like the gdkx.h header in GTK+ for X11 calls)
  clutter_backend_get_stage()
  clutter_backend_get_event()
  clutter_backend_peek_event()
  clutter_backend_put_event()
        -- right now, there's no function to access the default
           backend; a clutter_backend_get_default() will be added
           in the next days
  CLUTTER_FLAVOUR
        -- a macro that evaluates to the current backend name
           as a string; maybe we should split it like the version
           and have a CLUTTER_FLAVOUR_S
  clutter_events_pending()
  clutter_event_get()
  clutter_event_peek()
  clutter_event_put()
        -- these are wrappers around the ClutterBackend API calls
  clutter_event_get_time()
  clutter_event_get_state()
  clutter_event_get_coords()
  clutter_button_event_button()
        -- convenience functions for accessing events fields
  clutter_get_debug_enabled()
  clutter_get_show_fps()
  clutter_get_vblank_method()
        -- renamed for better readability
  clutter_stage_fullscreen()
  clutter_stage_unfullscreen()
  clutter_stage_show_cursor()
  clutter_stage_hide_cursor()
        -- wrappers around the stage properties
    clutter_stage_flush()
        -- flushes the stage viewport; this might go, though

- Removals:
  clutter_util_trap_x_errors()
  clutter_util_untrap_x_errors()
        -- both have been moved into the clutter-glx backend
  clutter_key_event_time()
  clutter_button_event_time()
        -- merged into clutter_event_get_time
  clutter_key_event_state()
        -- merged into clutter_event_get_state
  clutter_button_event_x()
  clutter_button_event_y()
        -- merged into clutter_event_get_coords
  CLUTTER_INIT_ERROR_OPENGL
        -- removed this error code, since the initialisation sequence
           now depends on the backend used
  clutter_xdisplay()
  clutter_xscreen()
  clutter_root_xwindow()
        -- moved into the clutter-glx backend
  clutter_want_debug()
  clutter_stage_get_xvisual()
  clutter_stage_get_xwindow()
  clutter_stage_set_xwindow_foreign()

+++

obviously, the API can still change and all my work of going through the
svn diff might be for nothing (;-)) but I think the API is pretty solid
as it is, so you are probably looking at how clutter 0.4 will look like.

as usual, feedback and suggestions are always welcome.

ciao,
 Emmanuele.

-- 
Emmanuele Bassi, ebassi@o-hand.com
OpenedHand Ltd.

-- 
To unsubscribe send a mail to clutter+unsubscribe@o-hand.com