-Clutter README.
-===============
+README for Clutter @CLUTTER_VERSION@
+===============================================================================
-This is Clutter 0.3. Clutter is a GObject based user interface toolkit
-intended for the creation of fast, visually bespoke and impressive
-applications. Open GL is used for rendering.
+Clutter is an open source software library for creating fast, compelling,
+portable, and dynamic graphical user interfaces.
-Its not meant to be a full featured GUI toolkit for regular desktop
-apps nor provide a general interface to *all* OpenGL functionality.
+REQUIREMENTS
+-------------------------------------------------------------------------------
Clutter currently requires:
- * GLib >= 2.10.0
- * GdkPixbuf
- * Pango 1.x
- * OpenGL >= 1.2 or OpenGL ES 1.1
- * GLX, SDL or an EGL Implementation
-
-The official website is:
- http://www.clutter-project.org
-The Clutter blog is at
- http://www.clutter-project.org/blog
-To subscribe to the Clutter mailing list, send mail to:
- clutter+subscribe@o-hand.com
-The official mailing list archive is:
- http://lists.o-hand.com/clutter/
-New bug page on Bugzilla:
- http://bugzilla.o-hand.com/enter_bug.cgi?product=Clutter
-
-Clutter is LGPL licensed.
-
-INSTALLATION
-====
-See the INSTALL file
+ • GLib ≥ @GLIB_REQ_VERSION@
+ • Cogl ≥ @COGL_REQ_VERSION@
+ • JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@
+ • Atk ≥ @ATK_REQ_VERSION@
+ • Cairo ≥ @CAIRO_REQ_VERSION@
+ • PangoCairo ≥ @PANGO_REQ_VERSION@
+
+When building the X11 backend, Clutter depends on the following extensions:
+
+ • XComposite ≥ @XCOMPOSITE_REQ_VERSION@
+ • XDamage
+ • XExt
+ • XFixes ≥ @XFIXES_REQ_VERSION@
+ • XInput (1.x or 2.x)
+ • XKB
+
+When building the Wayland backend, Clutter also depends on:
+
+ • wayland-client
+ • xkbcommon
+
+When building the GDK backend, Clutter also depends on:
+
+ • gdk-3.0 > @GDK_REQ_VERSION@
+
+When building the CEx100 backend, Clutter also depends on:
+
+ • libgdl
+
+If you are building the API reference you will also need:
+
+ • GTK-Doc ≥ @GTK_DOC_REQ_VERSION@
+
+If you are building the additional documentation you will also need:
+
+ • xsltproc
+ • jw (optional, for generating PDFs)
+
+If you are building the Introspection data you will also need:
+
+ • GObject-Introspection ≥ @GI_REQ_VERSION@
+
+GObject-Introspection is available from:
+
+ git://git.gnome.org/gobject-introspection
+
+If you want support for profiling Clutter you will also need:
+
+ • UProf ≥ @UPROF_REQ_VERSION@
+
+UProf is available from:
+
+ git://github.com/rib/UProf.git
+
+RESOURCES
+-------------------------------------------------------------------------------
+
+The official Clutter website is:
+
+ http://www.clutter-project.org/
+
+The API references for the latest stable release are available at:
+
+ http://docs.clutter-project.org/docs/clutter/stable/
+ http://docs.clutter-project.org/docs/cogl/stable/
+ http://docs.clutter-project.org/docs/cally/stable/
+
+The Clutter Cookbook is available at:
+
+ http://docs.clutter-project.org/docs/clutter-cookbook/@CLUTTER_API_VERSION@/
+
+New releases of Clutter are available at:
+
+ http://source.clutter-project.org/sources/clutter/
+ http://download.gnome.org/sources/clutter/
+
+The Clutter blog is available at:
+
+ http://www.clutter-project.org/blog/
+
+To subscribe to the Clutter mailing lists and read the archives, use the
+Mailman web interface available at:
+
+ http://lists.clutter-project.org/
+
+New bug page on Bugzilla:
+
+ http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
+
+Clutter is licensed under the terms of the GNU Lesser General Public
+License, version 2.1 or (at your option) later.
+
+BUILDING AND INSTALLATION
+-------------------------------------------------------------------------------
+
+To build Clutter from a release tarball, the usual autotool triad should
+be followed:
+
+ $ ./configure
+ $ make
+ # make install
+
+To build Clutter from a Git clone, run the autogen.sh script instead
+of the configure one. The autogen.sh script will run the configure script
+for you, unless the NOCONFIGURE environment variable is set to a non-empty
+value.
+
+See also the wiki page:
+
+ http://wiki.clutter-project.org/wiki/BuildingClutter
+
+Clutter has additional command line options for the configure script:
+
+ --enable-debug=[no/minimum/yes]
+ Controls Clutter debugging level:
+
+ yes:
+ All GLib asserts, checks and support for runtime Clutter
+ debugging notes through CLUTTER_DEBUG. This is the default
+ value for developers snapshots.
+
+ minimum:
+ Just GType cast checks and support for runtime Clutter
+ debugging notes through CLUTTER_DEBUG. This is the default
+ for stable releases.
+
+ no:
+ No GLib asserts or checks and no support for runtime Clutter
+ debugging notes. Only use in extreme performance and/or size
+ optimization cases, though it is strongly discouraged.
+
+ --enable-maintainer-flags=[no/yes/error]
+ Use strict compiler flags. This defaults to 'yes' for building from
+ Git to 'no' for tarball releases. If 'error' is used, then -Werror
+ will be enabled (if available).
+
+ --enable-gtk-doc
+ use gtk-doc to build API documentation (default=no). Requires gtk-doc
+ present on the target system.
+
+ --enable-docs=[no/yes]
+ Build additional documentation. Requires xsltproc for DocBook
+ conversion, and optionally jw for PDF generation.
+
+ --enable-gcov=[no/yes]
+ Build Clutter with coverage report support, provided by gcov. This
+ feature only works with the GNU Compiler Suite and gcov installed.
+
+ --enable-profile=[no/yes]
+ Build Clutter with profiling instrumentation. Requires the GNU
+ C Compiler and the UProf library.
+
+ --disable-tests
+ Disable building the Clutter tests suite.
+
+ --disable-examples
+ Disable building the Clutter API reference examples.
+
+ --enable-deprecated=[yes/no]
+ Whether deprecated symbols should be available when compiling Clutter.
+
+ --disable-Bsymbolic
+ Disable linking with -Bsymbolic.
+
+ --enable-x11-backend=[yes/no/check]
+ Enable the X11 backend. (default=check)
+
+ --enable-win32-backend=[yes/no/check]
+ Enable the native Microsoft Windows backend. (default=check)
+
+ --enable-quartz-backend=[yes/no/check]
+ Enable the native Quartz backend. (default=check)
+
+ --enable-gdk-backend=[yes/no/check]
+ Enable the GDK backend. (default=check)
+
+ --enable-wayland-backend=[yes/no]
+ Enable the Wayland client backend. (default=no) [EXPERIMENTAL]
+
+ --enable-cex100-backend=[yes/no]
+ Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]
+
+ --enable-egl-backend=[yes/no]
+ Enable the EGL framebuffer backend. (default=no)
+
+ --enable-tslib-input=[yes/no]
+ Enable the TSLib input backend. (default=no) [EXPERIMENTAL]
+
+ --enable-evdev-input=[yes/no]
+ Enable the evdev input backend. (default=no) [EXPERIMENTAL]
+
+See also the INSTALL file generated by autotools for further information.
+
+VERSIONING
+-------------------------------------------------------------------------------
+
+Clutter uses the common "Linux kernel" versioning system, where
+even-numbered minor versions are stable and odd-numbered minor
+versions are development snapshots.
+
+Different major versions break both API and ABI but are parallel
+installable. The same major version with differing minor version is
+expected to be ABI compatible with other minor versions; differing
+micro versions are meant just for bug fixing. On odd minor versions
+the newly added API might still change.
+
+The micro version indicates the origin of the release: even micro
+numbers are only used for released archives; odd micro numbers are
+only used on the Git repository.
+
+HACKING
+-------------------------------------------------------------------------------
+
+If you want to hack on and improve Clutter check the HACKING file for
+general implementation guidelines, and the HACKING.backends for
+backend-specific implementation issues.
+
+The CODING_STYLE file contains the rules for writing code conformant to the
+style guidelines used throughout Clutter. Remember: the coding style is
+mandatory; patches not conforming to it will be rejected by default.
+
+BUGS
+-------------------------------------------------------------------------------
+
+Bugs should be reported to the Clutter Bugzilla at:
+
+ http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
+
+You will need a Bugzilla account.
+
+In the report you should include:
+
+ • what system you're running Clutter on;
+ • which version of Clutter you are using;
+ • which version of GLib, Cogl, and OpenGL (or OpenGL ES) you are using;
+ • which video card and which drivers you are using, including output of
+ glxinfo and xdpyinfo (if applicable);
+ • how to reproduce the bug.
+
+If you cannot reproduce the bug with one of the tests that come with Clutter
+source code, you should include a small test case displaying the bad
+behaviour.
+
+If the bug exposes a crash, the exact text printed out and a stack trace
+obtained using gdb are greatly appreciated.
+
+CONTRIBUTING
+-------------------------------------------------------------------------------
+
+Patches should be submitted using Bugzilla. Patches fixing a bug should be
+attached to the bug report; patches for new features or for fixing bugs not
+yet reported should be attached to a newly opened bug.
+
+Patches should always be in the unified diff format, using:
+
+ diff -Nuarp clutter.source clutter.patched > clutter-patch.diff
+
+If diffing against the Git repository, you should use:
+
+ git diff > clutter-patch.diff
+
+Or, better: commit locally and use `git format-patch` to generate a patch
+containing authorship details, so that members of the Clutter development
+team can credit your contribution properly.
+
+Another useful tool for interacting with Git and Bugzilla is git-bz(1):
+
+ http://git.fishsoup.net/man/git-bz.html
+
+Which is available here:
+
+ http://git.fishsoup.net/cgit/git-bz/
+
+Patches submitted against Clutter have to pass the conformance test suite, or,
+if possible, add new unit tests for the conformance test suite in case of new
+features. Ensure you run the conformance test suite every for every patch you
+wish to submit, by using:
+
+ cd tests/conform && make test
+
+and verifying that the test suite passes.
RELEASE NOTES
-====
+-------------------------------------------------------------------------------
Relevant information for developers with existing Clutter applications
-wanting to port to newer releases;
+wanting to port to newer releases (see NEWS for general information on new
+features).
+
+Release Notes for Clutter 1.10
+-------------------------------------------------------------------------------
+
+• The ClutterActor::paint, ClutterActor::queue-redraw, and
+ ClutterActor::queue-relayout signals are now annotated as not allowing
+ signal emission hooks; this enables some optimization inside GLib, and
+ given the amount of emissions these three signals have, we want to get
+ through all the fast paths we can.
+
+• The ClutterActorBox parameter of the ClutterActor::allocation-changed
+ signal is now marked as G_SIGNAL_TYPE_STATIC_SCOPE.
+
+• The clutter-stage-window.h header is not installed any more; this header
+ was never meant to be public in the first place, and nothing could have
+ been implementing the ClutterStageWindow interface and use it with Clutter.
+
+• ClutterActor will call its unmap() implementation when it is removed from
+ its parent. This may happen after the ClutterActor::destroy signal has been
+ emitted, i.e. during its dispose(). Prior to 1.10, calling the
+ clutter_actor_destroy() function would unmap the actor first, and then
+ emit the destroy signal. This means that extra care should be used when
+ overriding the map() and unmap() virtual functions, to avoid dereferencing
+ NULL pointers. It is also worthy of note that since Clutter 1.8, overriding
+ map() or unmap() is not required any more for subclasses of ClutterActor
+ that have children, as ClutterActor will automatically do the right thing
+ inside its own implementation, and map or unmap its children when needed.
+
+• ClutterBox and ClutterGroup have been deprecated. ClutterActor should be
+ used directly, instead. Since ClutterStage inherits from ClutterGroup, the
+ instance and class structures are still available, but subclassing Group
+ is strongly disencouraged.
+
+• ClutterContainer provides default implementations for add(), remove(),
+ foreach(), raise(), lower(), and sort_depth_order(); this means that
+ overriding these virtual functions is now deprecated, and developers
+ should only implement ClutterContainer for classes providing child
+ properties.
+
+• ClutterActor is not an abstract type any more, and can be instantiated
+ either through clutter_actor_new() or through g_object_new().
+
+• ClutterActor now implements ClutterContainer, and takes over the entire API
+ for modifying the scene graph; this means that every actor can have children
+ and it's not necessary any more to implement the ClutterContainer interface.
+ ClutterActor provides new API to replace clutter_actor_set_parent() and
+ clutter_actor_unparent(), as well as a default implementation of every
+ Container virtual function. Existing actors overriding ClutterContainer and
+ providing an alternate implementation will continue to work, even though it
+ is strongly encouraged to port to the new API.
+
+• The ClutterActor::destroy signal is going to be emitted at the beginning
+ of the dispose sequence of a ClutterActor, instead of the end. This allows
+ to access the state of the actor being destroyed, instead of just being
+ able to use its pointer. This may expose bugs in code that does not check
+ for NULL actor pointers.
+
+• The long since broken depth cueing support in ClutterStage has been
+ deprecated; the fixed pipeline fog API has been pretty much useless
+ since the switch to colors and textures with premultiplied alpha
+ channels. Setting ClutterStage:use-fog to TRUE has no visible results,
+ and querying the :use-fog and :fog properties will always yield the
+ default values.
+
+• ClutterDeformEffect switched from using CoglVertexBuffer to using the
+ CoglPrimitive API internally, to improve performance and use non-deprecated
+ Cogl API. CoglPrimitive converts COGL_WRAP_MODE_AUTOMATIC to
+ COGL_WRAP_MODE_CLAMP_TO_EDGE, unlike CoglVertexBuffer which converts it to
+ COGL_WRAP_MODE_REPEAT. This prevents artifacts when sampling texture
+ coordinates outside the [ 0, 1 ] range. This change may cause the back
+ texture to not be painted if its coordinates go outside the allowed range,
+ for instance when using a custom transformation matrix on the back material
+ used by the ClutterDeformEffect.
+
+• The "default stage" has been deprecated; since the 1.0 release, the default
+ stage creation was deferred to the call to clutter_stage_get_default(), and
+ the preferred way for getting a ClutterStage was calling clutter_stage_new()
+ instead. On platforms that do not support multiple stages, attempting to
+ create more than one stage will lead to an error, and Clutter will abort.
+
+• Clutter can support multiple backends in the same shared library. Only one
+ windowing or input backend can be used at run time. As a result of this
+ change, the shared library name used by Clutter has changed from:
+
+ libclutter-<flavour>-<API version>.so
+
+ to:
+
+ libclutter-<API version>.so
+
+ The pkg-config file has been updated accordingly. Until the next major API
+ break, Clutter will ship compatibility links for all the previous "flavours"
+ that were available in versions < 1.10; this allows applications dynamically
+ linking against Clutter, or using dlopen(), to keep working. For libraries
+ and applications dynamically linking against Clutter, though, it is still
+ recommended to recompile to make sure that the most recent version is being
+ used. Language bindings using GObject Introspection will automatically use
+ the new shared library without requiring any change.
+
+• The windowing system backend for the CE3100 and CE4100 platforms using the
+ libgdl library is now implemented as a separate backend instance, instead
+ of being a sub-flavour of the EGL native framebuffer backend. This change
+ introduces a new header file, under $includedir/clutter-1.0/clutter/cex100,
+ which should be included to access the CEx100-specific API. The API and
+ ABI of the platform API has not been changed, though it should still be
+ considered experimental.
+
+• As of 1.10 it is not necessary any more to call clutter_threads_init() to
+ initialize threading support in Clutter; after the changes in GLib 2.32,
+ threading support in Clutter is always enabled. The rules on how to use
+ Clutter from multiple threads haven't changed.
+
+• Deprecated API is now marked using the CLUTTER_DEPRECATED and the
+ CLUTTER_DEPRECATED_FOR annotations; these two annotations will result in
+ compiler warnings when attempting to use the deprecated API. It is possible
+ to disable deprecation warnings for Clutter by defining the
+ CLUTTER_DISABLE_DEPRECATION_WARNINGS symbol when compiling. The previous
+ deprecation symbol, CLUTTER_DISABLE_DEPRECATED, is only used for macros.
+
+• Deprecated functionality has been moved to separate header files, installed
+ under the $includedir/clutter-1.0/clutter/deprecated directory. These files
+ are still included by default by clutter/clutter.h.
+
+Release Notes for Clutter 1.8
+-------------------------------------------------------------------------------
+
+• Cogl has been split out of tree. Clutter depends on Cogl, so users should
+ not notice anything. Developers using pkg-config will gain an extra Cogl
+ dependency.
+
+• The clutter_actor_get_gid() and clutter_get_actor_by_gid() functions have
+ been deprecated. They should not have been public in the first place.
+
+• ClutterShader and its relative API have been deprecated. ClutterShaderEffect
+ and the effect API is the proper way to use GLSL shaders with ClutterActors.
+ It is possible to instantiate a ClutterShaderEffect directly.
+
+• ClutterText's paint volume has been implemented using the ink rectangle of
+ the PangoLayout used to paint, to allow culling to work properly even in
+ the case of glyphs spilling outside the logical rectangle.
+
+• Non fully opaque children of a non fully opaque actor will be composited
+ in an offscreen framebuffer object to preserve the correct overall opacity.
+ This changes the way non fully opaque actors are drawn, and might cause
+ some code relying on the old, unspecified behaviour to produce different
+ results.
+
+• ClutterBoxLayout layout algorithm has been changed to map the more mature
+ and more stable GtkBox one.
+
+• The ClutterText:editable property was incorrectly defined in the GParamSpec
+ as being TRUE by default, but it was initialized to FALSE. To avoid breaking
+ existing code, the default value inside the GParamSpec (and inside the
+ documentation) has been changed to FALSE as well.
+
+• The preferred way to draw inside a ClutterCairoTexture is connecting to
+ its ::draw signal, and calling the invalidate() method. The old pattern
+ of creating the Cairo context using the create() method is deprecated but
+ still working as intended.
+
+• ClutterScore has been deprecated; the preferred way to chain up multiple
+ animations is to use the ClutterAnimator or ClutterState classes.
+
+Release Notes for Clutter 1.6
+-------------------------------------------------------------------------------
+
+• The internal copy of JSON-GLib has been removed: Clutter now strictly
+ depends on the installed copy of this library. The --with-json configure
+ switch has been removed.
+
+• The ClutterBehaviour class and its sub-classes have been deprecated; the
+ Clutter API reference contains a migration guide to port code based on
+ behaviours to the implicit animations framework.
+
+• The ClutterTimeoutPool and clutter_frame_source_* API have been deprecated;
+ both API are not integrated in the Clutter main loop, and are not used
+ internally any longer, so they are of relative use.
+
+• It it not necessary any more to provide implementations for the
+ ClutterActor::map() and ClutterActor::unmap() virtual functions, even
+ for composite actors not implementing the ClutterContainer interface.
+
+• ClutterTimeline now guarantees that the ::new-frame signal will be
+ emitted at the beginning of the timeline, as well as guaranteeing that
+ the ::completed signal will be emitted at the end of the timeline.
+
+• ClutterActor will check for the enabled property of ClutterActorMeta
+ instances (actions, constraints and effects), and will not invoke
+ ClutterActorMeta functions on disabled instances. This removes the
+ requirement for checking the property inside the ClutterActorMeta
+ sub-classes.
+
+• ClutterActorBox, ClutterGeometry and ClutterVertex install a progress
+ function for ClutterInterval, allowing the interpolation of properties
+ using them as storage types.
+
+• ClutterColor's clutter_color_from_string() function accepts CSS3 color
+ specifications.
+
+• The previously unused "axes" field in the ClutterButtonEvent,
+ ClutterScrollEvent and ClutterMotionEvent structures is now used on
+ the X11-based backends with XInput support.
+
+• ClutterListModel will honour the filter function when calling
+ clutter_model_get_iter_at_row().
+
+• ClutterClickAction does not use a pointer grab any longer, and uses
+ a capture on the stage instead.
+
+• On all platforms which allow it, ClutterStage will ask the windowing
+ system for an explicit key focus when showing the stage window. This
+ can be disabled using clutter_stage_set_accept_focus().
+
+Release Notes for Cogl 1.6
+-------------------------------------------------------------------------------
+
+• Cogl may internally optimise cogl_read_pixels when only a single
+ pixel is drawn and the entire scene is comprised of solid colour
+ rectangles. Instead of actually rendering the rectangles it will
+ compute the single pixel value in software. This effectively means
+ that Clutter can do software picking without any API changes.
+
+• Internally Cogl now has a GLSL backend as well as the ARBfp and
+ fixed function backends. By default, this backend has the lowest
+ priority but it can be explicitly enabled by setting the
+ COGL_DEBUG environment variable, e.g.:
+
+ export COGL_DEBUG=disable-fixed,disable-arbfp
+
+ for builds of Clutter with debug support enabled.
+
+• Cogl will internally now cache generated ARBfp programs so that it
+ should be able to reuse a previous program even if it was generated
+ for an unrelated CoglMaterial. This makes using one-shot materials
+ less expensive than before although it is still not recommended.
+
+Release Notes for Clutter 1.4
+-------------------------------------------------------------------------------
+
+• ClutterLayoutManager sub-classes overriding the set_container() virtual
+ function should chain up to the parent class's implementation.
+
+• The ClutterTexture:filename property is now readable, as well as writable;
+ this allows querying the Texture for the filename storing the image data.
+ The value will be unset when using the set_from_*_data() family of
+ functions.
+
+• If both the :sync-size and the :keep-aspect-ratio properties of a
+ ClutterTexture are set to TRUE, then the texture actor will update its
+ ClutterActor:request-mode property depending on the orientation of the
+ image data - height-for-width for landscape, and width-for-height for
+ portrait. Square image data will default to height-for-width, like all
+ actors. You can still explicitly override the :request-mode value, or
+ you can unset the :sync-size property to control the size yourself.
+
+• All the key symbol macros have been renamed from CLUTTER_* to
+ CLUTTER_KEY_*. The old names are still available inside the
+ clutter-keysyms-compat.h header, which is included by clutter-keysyms.h
+ unless CLUTTER_DISABLE_DEPRECATED is defined.
+
+• The internal copy of json-glib is now deprecated. Building Clutter will
+ default to the system copy and requires an explicit --with-json=internal
+ to override the check.
+
+Release Notes for Clutter 1.2
+-------------------------------------------------------------------------------
+
+* ClutterStageManager is now publicly available and documented API.
+
+* Clutter now depends on the system copy of JSON-GLib, and will fall
+ back to the internal copy only if JSON-GLib is not installed.
+
+* ClutterActor:opacity is now defined using GParamSpecUint instead of
+ GParamSpecUchar; the same interval of [ 0, 255 ] applies, and GValue
+ has internal transformation functions for converting between G_TYPE_UINT
+ and G_TYPE_UCHAR, so this change should be fully transparent to the
+ user of the code.
+
+* On X11 Clutter will emulate XKB's detectable key auto-repeat; this means
+ that when holding down a key, Clutter will emit multiple CLUTTER_KEY_PRESS
+ events and a single CLUTTER_KEY_RELEASE event instead of a list of
+ CLUTTER_KEY_PRESS and CLUTTER_KEY_RELEASE pairs.
+
+* On X11 and Win32 the default Stage is created when
+ clutter_stage_get_default() is called for the first time, and not as
+ part of the stage initialization.
+
+Cogl API changes for Clutter 1.2
+-------------------------------------------------------------------------------
+
+* cogl_viewport is now deprecated in favour of cogl_set_viewport which
+ accepts a viewport offset.
+
+* cogl_clip_push() is now deprecated and new code should use
+ cogl_clip_push_rectangle() instead. The old API wasn't consistent with other
+ Cogl APIs that specify model space rectangles using (x0,y0)(x1,y1) pairs.
+
+* cogl_clip_push_window_rect() is now deprecated and new code should use
+ cogl_clip_push_window_rectangle(). The old API shouldn't have been defined
+ to take floats and the abbreviation wasn't consistent with other Cogl API.
+
+* cogl_clip_stack_save() and cogl_clip_stack_restore() are deprecated, as
+ the functionality is redundant now that offscreen draw buffers own their
+ clip state and switching to/from offscreen rendering will automatically
+ save and restore the clip state.
+
+* cogl_material_copy() was added. It is advised that developers use
+ this instead of cogl_material_new() when creating a material that is in some
+ way derived from another. This will allow Cogl to track material
+ ancestries/similarities and reduce the cost of GPU state changes.
+
+* cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now
+ deprecated and new code should use the cogl_framebuffer_* API instead.
+ Code that previously did:
+ cogl_push_draw_buffer ();
+ cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer);
+ /* draw */
+ cogl_pop_draw_buffer ();
+ can now be re-written as:
+ cogl_push_framebuffer (buffer);
+ /* draw */
+ cogl_pop_framebuffer ();
+
+* All cogl_<type>_ref() and cogl_<type>_unref() functions have been
+ deprecated, and superceded by cogl_handle_ref() and cogl_handle_unref()
+ respectively.
+
+* The cogl_check_extension() function has been deprecated. This function
+ was never meant to be public, since it depends on calling glGetString()
+ before its invocation. Users of this function can be replaced by the
+ equivalent code:
+
+ gl_ext = glGetString (GL_EXTENSIONS);
+ - has_ext = cogl_check_extension (ext_name, gl_ext);
+ + has_ext = strstr (gl_ext, ext_name) != NULL ? TRUE : FALSE;
+
+Release Notes for Clutter 1.0
+-------------------------------------------------------------------------------
+
+* The clutter_actor_set_shader_param() function now takes a
+ GValue, which can be set using the clutter_value_set_shader()
+ family of functions. The floating point wrapper has been
+ rename clutter_actor_set_shader_param_float() to match the newly
+ added clutter_actor_set_shader_param_int().
+
+* The Pango renderer API has been exposed as public API, after
+ a full rename from PangoClutter to CoglPango, to avoid namespace
+ collisions with upstream Pango. The Pango font map, renderer and
+ glyph cache can be used by third party code and depend only on
+ COGL.
+
+* Both Clutter and COGL only allow including <clutter/clutter.h>
+ and <cogl/cogl.h> directly, respectively. This allows avoiding
+ breaking API every time a type definition is moved across
+ headers, and improves the reliability of third party code against
+ internal refactorings.
+
+* COGL has an internal Color type, used to store a color definition
+ that can be efficiently used with the least amount of conversions
+ by both the GL and GLES implementations. The COGL API has been
+ changed to drop the usage of ClutterColor in favour of CoglColor.
+
+* The fixed point API implementation Clutter uses internally has been
+ moved from the Clutter namespace to the COGL one.
+
+* ClutterLabel and ClutterEntry have been removed from the API, as
+ both have been superceded by the ClutterText actor.
+
+* ClutterCloneTexture has been removed from the API; in its place,
+ there is a generic ClutterClone actor which allows to "clone"
+ any existing actors -- even composite ones -- without using
+ frame buffer objects (FBOs).
+
+* The ClutterEffectTemplate and clutter_effect_* functions have been
+ superceded by ClutterAnimation and thus removed from the public API.
+
+* The ClutterBehaviourBspline has been superceded by the usage of
+ ClutterPath inside ClutterBehaviourPath, and thus removed from the
+ public API.
+
+* ClutterColor API has received a much needed review to increase its
+ consistency. This has led to the following changes:
+
+ - clutter_color_parse() has been renamed to clutter_color_from_string()
+ and the order of the arguments has been changed
+
+ - the factor argument of clutter_color_shade() has been swapped with
+ the return location for the new color
+
+ - the fixed point entry points have been removed
+
+ - clutter_color_from_hls() and clutter_color_to_hls() do not
+ normalize the values in the [ 0, 255 ] interval but use the
+ correct HLS intervals:
+
+ Hue: [ 0, 360 )
+ Luminance: [ 0, 1 ]
+ Saturation: [ 0, 1 ]
+
+* The ClutterFixed symbols have been completely removed: fixed-point
+ public entry points now take a CoglFixed.
+
+* The -x and -u API have been removed. All the pixel-based API now
+ takes a float to allow sub-pixel precision; this is true also for
+ properties. WARNING: functions with variadic arguments (like
+ g_object_set(), g_object_get() and clutter_actor_animate()) do not
+ behave very well when dealing with integers instead of expected
+ floating point values, and vice versa. On 32bit machines it will
+ most likely lead to a crash. So:
+
+ g_object_set (actor, "width", 100, NULL);
+
+ is incorrect, and should be changed in:
+
+ g_object_set (actor, "width", 100.0, NULL);
+
+* Composite actors that do not implement the Container interface
+ should implement the following virtual functions:
+
+ - void map (ClutterActor*)
+ - void unmap (ClutterActor*)
+
+ and chain up to the parent's implementation after calling
+ clutter_actor_map() or clutter_actor_unmap() on their children.
+
+* Actors implementing the Container interface that have private
+ children that are not meant to be added/removed through the
+ Container API should implement the:
+
+ - void foreach_with_internals (ClutterContainer*,
+ ClutterCallback,
+ gpointer);
+
+ virtual function.
+
+* Actors that perform direct transformations using the COGL API inside
+ their paint() implementation should override the apply_transform()
+ virtual function instead. Implementations of the apply_transform()
+ vfunc must chain up to the implementation of the parent class.
+
+* The ClutterUnit type and the CLUTTER_UNITS_* conversion macros have
+ been removed: all Actors are now using sub-pixel precision directly
+ throughout the API. The new ClutterUnits type has been added as a
+ generic opaque storage for logical distance values.
+
+* Timelines are now fully time-based: all the frame-related properties
+ and methods have been removed. ClutterTimeline::new-frame will provide
+ the elapsed milliseconds since the beginning of the Timeline, instead
+ of the current frame number. The clutter_timeline_new() constructor
+ takes the duration of the timeline in milliseconds, and thus it replaces
+ the clutter_timeline_new_for_duration() variant.
+
+Cogl API changes for Clutter 1.0
+-------------------------------------------------------------------------------
+
+* All drawing functions now use a source material to determine how geometry is
+ filled. The source material is set via cogl_set_source. Or the convenience
+ functions cogl_set_source_color and cogl_set_source_texture.
+
+ "drawing functions" include: cogl_rectangle, cogl_texture_rectangle,
+ cogl_texture_multiple_rectangles, cogl_texture_polygon (though the
+ cogl_texture_* funcs have been renamed; see below for details),
+ cogl_path_fill/stroke and cogl_vertex_buffer_draw*.
+
+ cogl_texture_rectangle, cogl_texture_multiple_rectangles and
+ cogl_texture_polygon no longer take a texture handle; instead the current
+ source material is referenced. The functions have also been renamed to:
+ cogl_rectangle_with_texture_coords, cogl_rectangles_with_texture_coords
+ and cogl_polygon respectively.
+
+ Most code that previously did:
+ cogl_texture_rectangle (tex_handle, x, y,...);
+ needs to be changed to now do:
+ cogl_set_source_texture (tex_handle);
+ cogl_rectangle_with_texture_coords (x, y,....);
+
+ In the less likely case where you were blending your source texture with a
+ color like:
+ cogl_set_source_color4ub (r,g,b,a); /* (where r,g,b,a isn't just white) */
+ cogl_texture_rectangle (tex_handle, x, y,...);
+ you will need your own material to do that:
+ material = cogl_material_new ();
+ cogl_material_set_color4ub (r,g,b,a);
+ cogl_material_set_layer (material, 0, tex_handle));
+ cogl_set_source_material (material);
+
+ Code that uses the texture coordinates, 0, 0, 1, 1 don't need to use
+ cogl_rectangle_with_texture_coords since these are the coordinates that
+ cogl_rectangle will use.
+
+ For cogl_texture_polygon; as well as dropping the texture handle, the
+ n_vertices and vertices arguments were transposed for consistency. So
+ code previously written as:
+ cogl_texture_polygon (tex_handle, 3, verts, TRUE);
+ need to be written as:
+ cogl_set_source_texture (tex_handle);
+ cogl_polygon (verts, 3, TRUE);
+
+* The arguments to cogl_rectangle, cogl_path_rectangle and
+ cogl_path_round_rectangle have been changed - for consistency - from
+ x, y, width, height, to x1, y1, x2, y2.
+
+* A CoglMatrix type and utility API has been added; this is currently used to
+ support describing texture matrices.
+
+* cogl_alpha_func has been removed, since this is now controlled using the
+ material API via cogl_material_set_alpha_test_function ()
+
+* A Cogl Vertex Buffer API has been added that allows you to efficiently
+ manage arrays of vertex attributes in buffers that may be stored on
+ the GPU. These allow you to avoid the costs of repeatedy validating
+ vertex data and mapping it into the GPU.
+
+* cogl_scale now supports scaling on the z axis
+
+* cogl_clip_set* and cogl_clip_unset have been renamed to cogl_clip_push and
+ cogl_clip_pop respectively so they self document their stacking semantics.
+
+* cogl_paint_init was renamed to cogl_clear and no longer disables lighting and
+ fogging. cogl_clear also now takes a mask of the auxiliary buffers you want
+ to clear so you can avoid redundant clears of buffers you aren't using.
+
+* cogl_fog_set was renamed to cogl_set_fog and it now takes a mode argument
+ giving control over the fogging blend factor equation, so that the
+ density argument isn't just ignored. A cogl_disable_fog function was
+ also added.
+
+* cogl_get_*_matrix were changed to use the CoglMatrix type instead of
+ GLfloat m[16] arrays.
+
+* cogl_offscreen_blit_region, cogl_offscreen_blit were removed since they were
+ only implemnted for GL, not GLES, and it was assumed no one was using them.
+
+* cogl_offscreen_new_multisample was removed since it only ever returned
+ COGL_INVALID_HANDLE so it wasn't usefull.
+
+* The COGL_MASK_BUFFER type was removed, since there should be nicer ways of
+ exposing color mask if anyone wants it later. It was assumed that no one was
+ using this currently.
+
+* COGLenum, COGLint and COGLuint which were simply typedefs for
+ GL{enum,int,uint} have been removed from the API and replaced with
+ specialised enum typedefs, int and unsigned int. These were causing
+ problems for generating bindings and also considered poor style.
+
+* The cogl texture filter defines CGL_NEAREST and CGL_LINEAR etc are now
+ replaced by a namespaced typedef 'CoglTextureFilter' so they should be
+ replaced with COGL_TEXTURE_FILTER_NEAREST and COGL_TEXTURE_FILTER_LINEAR etc.
+
+* The shader type defines CGL_VERTEX_SHADER and CGL_FRAGMENT_SHADER are handled
+ by a CoglShaderType typedef and should be replaced with
+ COGL_SHADER_TYPE_VERTEX and COGL_SHADER_TYPE_FRAGMENT.
+
+* cogl_shader_get_parameteriv has been replaced by cogl_shader_get_type and
+ cogl_shader_is_compiled. More getters can be added later if desired.
+
+* cogl_enable_depth_test has been renamed to cogl_set_depth_test_enabled and
+ a corresponding cogl_get_depth_test_enabled function has been added.
+
+Release Notes for Clutter 0.8
+-------------------------------------------------------------------------------
+
+* The COGL GL wrapper API has been completely overhauled and now
+ contains many new features including new greatly improved texture
+ abstractions (slicing, mipmapping, deformations etc, greatly
+ simplifying ClutterTexture), image loading and abstraction, path
+ based primitive drawing, clipping, and improved FBO and shader
+ support. It is now also fully documented.
+
+* GL Texture Rectangle ext is no longer used, the regular 2D NPOTS
+ extension is preffered instead but not required.
+
+* Clutter now has basic suppport for multiple input devices assuming
+ the backend supports it (currently X11 based via XInput and Fruity
+ backends). New API supporting this includes
+ clutter_event_get_device_id, clutter_get_input_device_for_id,
+ clutter_grab_pointer_for_device & clutter_ungrab_pointer_for_device.
+
+ XInput support needs to be explicitly enabled at runtime by calling
+ clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput ()
+ can then be called after to check if XInput extension present and use-able.
+
+* The functions that return the transformed position of an actor have
+ been renamed to be more explicit about it:
+
+ clutter_actor_get_abs_position - clutter_actor_get_transformed_position
+ clutter_actor_get_abs_size - clutter_actor_get_transformed_size
+
+ Their behaviour has not been changed.
+
+* To increase portability, Clutter does not strictly depend on
+ GdkPixbuf anymore; this means that you will have to include
+ <gdk-pixbuf/gdk-pixbuf.h> yourself if you are operating with
+ GdkPixbuf objects and not including that header. The GdkPixbuf-based
+ API has been removed from Clutter core:
+
+ clutter_texture_new_from_pixbuf
+ clutter_texture_set_pixbuf
+ clutter_texture_get_pixbuf
+
+ are all deprecated functions. It is still possible to load a GdkPixbuf
+ into a ClutterTexture with this sample code:
+
+ clutter_texture_set_from_rgb_data (texture,
+ gdk_pixbuf_get_pixels (pixbuf),
+ gdk_pixbuf_get_has_alpha (pixbuf),
+ gdk_pixbuf_get_width (pixbuf),
+ gdk_pixbuf_get_height (pixbuf),
+ gdk_pixbuf_get_rowstride (pixbuf),
+ gdk_pixbuf_get_has_alpha (pixbuf) ? 4
+ : 3,
+ 0,
+ &error);
+
+ ClutterTexture also now has a new filename property and
+ clutter_texture_new_from_file which is intended as an alternate to
+ common previous GdkPixbuf primary usage (i.e loading images from
+ disk).
+
+ To read texture data back into a pixbuf or system memory use a combination
+ of clutter_texture_get_cogl_texture & cogl_texture_get_data.
+
+ The clutter-gtk integration library has API for using GdkPixbuf with
+ ClutterTextures (among others).
+
+ ClutterTexture now supports a keep-aspect property which is set to FALSE
+ by default.
+
+* clutter_texture_from_actor will now reparent source actors if they
+ are not parented. This behaviour may change in future releases.
+ There are known not yet fixed issues with source actors that set
+ depth or use clipping.
+
+* The size negotiation API has been completely changed in order to allow
+ the creation of non-fixed layout managers. These functions have been
+ removed:
+
+ clutter_actor_request_coords()
+ clutter_actor_query_coords()
+
+ from the ClutterActor API, as well as their virtual functions inside
+ the ClutterActorClass. The size of an actor is now split into two
+ different concepts: the preferred size (width and height
+ separatedly) and the size that has been allocated by the container
+ to which that actor belongs. Clutter still defaults to the fixed
+ layout management (i.e ClutterGroup) of the actors, but supports
+ fluid layout managers written using the new API.
+
+ Composite actors (actors with 'private' children not implementing the
+ container interface) now need to implement an allocate method here pass
+ an allocation to any composite children.
+
+* Clutter now depends on PangoCairo for the font rendering. The PangoClutter
+ API is still considered semi-private and no guarantees are made on its
+ stability.
+
+* ClutterShader API has been slightly changed: the ClutterStage:bound
+ property, clutter_shader_bind() and clutter_shader_is_bound() have
+ been renamed to :compiled, clutter_shader_compile() and
+ clutter_shader_is_compiled(), respectively. The previously semi-private
+ clutter_shader_release_all() function is now not exported anymore.
+
+* ClutterStage is not an abstract type anymore: it can be instantiated
+ using clutter_stage_new() and it can be properly subclassed. If the
+ backend supports multiple stages, every stage will be a new window,
+ whose lifetime will have to be managed by the developer. Clutter will
+ still create the default stage, and guarantees that every call to
+ clutter_stage_get_default() will return exactly the same pointer.
+
+* Actors now have a new 'show-on-set-parent' property set to TRUE by
+ default. With this property set to TRUE, actors will automatically
+ have clutter_actor_show() called on them when a parent is set (i.e
+ added to a container).
+
+* Clutter now features support for multiple stages assuming supported
+ by the backend. See test-multistage.c for example of usage. This
+ does not change the automatic creation of the default stage.
+ A single GL context is used across all stages meaning GL resources
+ are shared.
+
+* There is now an experimental native iPod Touch/iPhone UIKit backend
+ named 'fruity'.
+
+* There is now an experimental native Win32 WGL backend.
+
+* COGL (and therefor Clutter) now optionally features initial support for
+ OpenGL ES 2.0. It features support for shaders.
+
+* Some more focused timeline unit tests have been added and some tweaks to
+ timeline semantics were made; E.g. For a 10 frame timeline here are some
+ points about the semantics:
+ - When you create a timeline it starts with current_frame_num == 0
+ - After starting a timeline, the first timeout is for current_frame_num == 1
+ (Notably it isn't 0 since there is a delay before the first timeout signals
+ so re-asserting the starting frame (0) wouldn't make sense.)
+ - For a non looping timeline the last timeout would be for
+ current_frame_num == 10
+ - For a looping timeline the timeout for current_frame_num == 10 would be
+ followed by a timeout for current_frame_num == 1 and frame 0 is considered
+ == frame 10.
+ - Asking for a timeline of N frames might better be described as asking for
+ a timeline of _length_ N.
+
+* The behaviour of clutter_actor_get_opacity() has been slightly changed;
+ instead of returning the composited opacity of the entire parents chain
+ of an actor, clutter_actor_get_opacity() does what you mean, and returns
+ the opacity set with clutter_actor_set_opacity(). The composited
+ opacity value is now returned by clutter_actor_get_paint_opacity().
+
+* Until 0.6, clutter_label_get_color() would have returned a ClutterColor
+ with the alpha component equal to the composited opacity of the label.
+ Now, clutter_label_get_color() returns a copy of the exact color set
+ with clutter_label_set_color().
+
+* The ClutterEntry actor will automatically handle key events inside
+ a key-press-event handler. This deprecates the usage of
+ clutter_entry_handle_key_event() to update the contents of the
+ entry using the ClutterKeyEvent.
+
+* The Clutter X11 and GLX backends feature support for wrapping external
+ X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX
+ extension if available and fallback to slower XGetImage copies if not.
+
+* ClutterContainer can have per child custom properties via ClutterChildMeta.
+
+Release Notes for Clutter 0.6
+-------------------------------------------------------------------------------
+
+* Now that every actor has events, the class signal handlers have been
+ removed from ClutterStageClass and moved into ClutterActorClass.
+
+* The CLUTTER_2BUTTON_PRESS and CLUTTER_3BUTTON_PRESS event types have been
+ removed in favour of the ClutterButtonEvent:click_count counter
+
+* X11 related called for glx and eglx backends are now shared and moved into
+ a clutter_x11 prefix.
+
+* Scaling with gravity functionality was replaced by more generic and
+ powerful anchor point.
+
+* The ClutterLayout interface, the ClutterBox and its implementations have
+ been moved outside Clutter core.
+
+* The Effects API has been simplified, and it only requires the final value
+ of the effect instead of both the start and end value.
+
+* The per-axis rotation API has been deprecated in favour of a single
+ pair of accessors, clutter_actor_set_rotation() and
+ clutter_actor_get_rotation().
+
+* Every actor sub-class that is overriding the ClutterActor::request_coords()
+ virtual function *must* chain up to the parent's implementation in order
+ to store the bounding box inside the ClutterActor private data.
+
+* It is now impossible to call clutter_actor_destroy() on the stage. Backends
+ will have to unset the CLUTTER_ACTOR_IS_TOPLEVEL private flag to actually
+ destroy the stage.
+
+* The default value of the ClutterLabel:wrap property has been changed from
+ TRUE to FALSE.
+
+* All the behaviours properties have been renamed to match the $PROPERTY-start
+ and $PROPERTY-end convention.
+
+* The clutter_group_add() function has been "undeprecated" and reimplemented
+ as a commodity macro; a clutter_stage_add() commodity macro has also been
+ added. Both macros just safely wrap clutter_container_add_actor().
+
+* The ClutterContainer::find_child_by_id() virtual function has been removed;
+ Clutter keeps track of every actor, so there's no need to recurse into
+ containers anymore.
+
+* The unused ClutterActor::set_depth() and ClutterActor::get_depth() virtual
+ functions have been removed.
+
+* It is now possible to roundtrip the string created by
+ clutter_color_to_string() to clutter_color_parse().
+
+* The amount of motion events is now being throttled using the default frame
+ rate setting as the base value to compute the default and maximum frequency
+ of motion events to be delivered to every actor.
+
+* ClutterAngle usage has been removed from the public API: it is an internal
+ optimization, which can be used for faster angle computations; users of
+ ClutterAngle now take a fixed point number in form of a ClutterFixed.
+
+* ClutterGravity usage when scaling has been superceded by the anchor point.
+
+* The precision of the clutter_sqrti() algorithm has been improved for small
+ values.
+
+* ClutterBehaviourScale constructor, scale properties and accessors have
+ been changed to accomodate the scaling factors on both the X and Y axis,
+ matching the clutter_actor_set_scale() function. This also changed the
+ clutter_effect_scale() function, which now accepts the final scale
+ factor on both the X and Y axis. The gravity property has also been
+ removed, as it behaved incorrectly with regards to the anchor point. When
+ scaling an actor using a BehaviourScale, the anchor point should be set
+ before applying the behaviour (remember to adjust the positioning as
+ well by factoring in the anchor point).
+
+* The clutter_do_event() is now public; it can be used to feed an event to
+ Clutter and let it generate the capture-bubble signal emissions; it should
+ not be used by applications.
+
+* In the X11-based backends, the DestroyNotify event is not propagated to
+ Clutter core if the stage is using a foreign window.
+
+* To avoid method name collisions between ClutterActor and ClutterEntry
+ in high-level languages, the clutter_entry_set_position() and
+ clutter_entry_get_position() functions have been renamed to
+ clutter_entry_set_cursor_position() and clutter_entry_get_cursor_position()
+ respectively.
+
+Release Notes for Clutter 0.4.0
+-------------------------------------------------------------------------------
+
+* clutter_actor_show_all does not recurse for groups at least (this is to
+ match the original group_show_all behaviour). This is like 0.3 but was
+ never noted.
+
+* ClutterBox API has changed: clutter_box_pack_start() and
+ clutter_box_pack_end() have been removed in favour of the clutter_box_pack()
+ API.
+
+* Both clutter_threads_enter() and clutter_threads_leave() have been
+ removed from the API, as they just created confusion and the wrong
+ idea that Clutter is either thread-safe or thread-aware. Full
+ thread-awareness is arriving in the next revision (see bug #429).
+
+* The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been
+ overhauled.
+
+Release Notes for Clutter 0.3.1
+-------------------------------------------------------------------------------
+
+* clutter_actor_apply_transform_to_point() parameters changed to use
+ ClutterVertices.
+
+* New 'Native API' backend expects EGL implementation to provide a
+ CreateNativeWindow() API call.
+
+* Exisiting X11 based egl backend public API calls now prefixed eglx.
Release Notes for Clutter 0.3
------------------------------
+-------------------------------------------------------------------------------
* ClutterTexture changes:
+ clutter_texture_set_pixbuf() now takes a GError paremeter.
clutter_texture_set_from_yuv_data().
* The GLX specific API has been moved to the GLX backend code and
- it's now under the ClutterGlx namespace.
+ it's now under the ClutterGlx namespace.
* The priority of the various users of the GLib main loop has been
reviewed and changed were necessary. Every paint is queued with a
* clutter_color_parse() now handles color definitions with alpha. Alpha
will default to fully Opaque rather than fully transparent if not specified.
-* The Clutter examples/ directory has been removed and replaced with a
+* The Clutter examples/ directory has been removed and replaced with a
tests/ directory.
-* Event API changes and event queue (Ebassi) .
-
-* Runtime options now dependant on backend.
-
-HACKING
-====
-If you want to hack on and improve clutter check the TODO file.
-
-BUGS
-====
-Bugs should be reported to the OpenedHand Bugzilla at:
-
- http://bugzilla.o-hand.com/enter_bug.cgi?product=Clutter
+* The ClutterEvent API has been changed, and specific functions have been
+ removed in favour of event-agnostic ones.
-You will need an account.
-
-In the report you should include:
-* what system you're running Clutter on;
-* which version of GLib, GdkPixbuf and OpenGL you are using;
-* which video card and which drivers you are using, including output of
- glxinfo and xdpyinfo.
-* how to reproduce the bug.
+* The ClutterStage::input-event signal has been removed. All the events now
+ emit the ClutterStage::event and ClutterStage::event-after signals, for
+ generic event handling.
-If you cannot reproduce the bug with one of the tests that come with Clutter
-source code, you should include a small test case displaying the bad
-behaviour.
-
-If the bug exposes a crash, the exact text printed out and a stack trace
-obtained using gdb are greatly appreciated.
+* Runtime options now dependant on backend.
-PATCHES
-====
-Patches should be submitted using Bugzilla. Patches fixing a bug should be
-attached to the bug report; patches for new features or for fixing bugs not
-yet reported should be attached to a newly opened bug. Patches should always
-be in the unified diff format.
+* ClutterGroup API to add, remove and list children has been deprecated in
+ favour of ClutterContainer API. The ClutterGroup::add and
+ ClutterGroup::remove signals have been deprecated:
+ ClutterContainer::actor-added and ClutterContainer::actor-removed should
+ be used instead.