README for Clutter @CLUTTER_VERSION@
===============================================================================
-Clutter is an open source software library for creating fast, compellin,
+Clutter is an open source software library for creating fast, compelling,
portable, and dynamic graphical user interfaces.
REQUIREMENTS
Clutter currently requires:
• 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@
- • OpenGL ≥ 1.3 (or 1.2+multitexturing), OpenGL ES 1.1 or OpenGL ES 2.0
- • GLX, SDL, WGL or an EGL Implementation
-Clutter also has optional dependencies:
+When building the X11 backend, Clutter depends on the following extensions:
- • GDK-Pixbuf ≥ @GDK_PIXBUF_REQ_VERSION@
-
-On X11, Clutter depends on the following extensions
-
- • XComposite ≥ 0.4
+ • XComposite ≥ @XCOMPOSITE_REQ_VERSION@
• XDamage
• XExt
- • XFixes ≥ 3
+ • XFixes ≥ @XFIXES_REQ_VERSION@
• XInput (1.x or 2.x)
• XKB
-When running the OpenGL flavor, Clutter requires at least version 1.3
-or 1.2 with the multitexturing extension. However to build Clutter
-you will need the latest GL headers which can be obtained from:
+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@
- http://www.khronos.org
+When building the CEx100 backend, Clutter also depends on:
+
+ • libgdl
If you are building the API reference you will also need:
http://www.clutter-project.org/
-The API reference for the latest stable release and unstable developers
-snapshot are available at:
+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/clutter/unstable/
+ 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:
New bug page on Bugzilla:
- http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
+ 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.
debugging notes. Only use in extreme performance and/or size
optimization cases, though it is strongly discouraged.
- --enable-cogl-debug=[no/minimum/yes]
- Controls COGL debugging level (default=minimum):
-
- yes:
- Support for COGL debugging notes through COGL_DEBUG and
- error checking for each GL primitive. This is useful mostly
- to debug COGL itself.
-
- minimum:
- Support for COGL debugging notes through COGL_DEBUG. This is
- the default for developers snapshots.
-
- no:
- Disable support for COGL runtime debugging notes.
-
--enable-maintainer-flags=[no/yes/error]
- Use strict compiler flags. This defaults to 'yes' for developers
- snapshots and to 'no' for stable releases. If 'error' is used, then
- -Werror will be enabled (if available).
+ 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
Build Clutter with profiling instrumentation. Requires the GNU
C Compiler and the UProf library.
- --enable-conform=[yes/no]
- Build the Clutter conformance test suite.
-
- --disable-Bsymbolic
- Disable linking with -Bsymbolic.
-
- --with-flavour=[glx/eglx/eglnative/osx/win32/fruity]
- Select the Clutter backend: (default=glx)
-
- glx:
- Fully featured GLX backend.
-
- opengl-egl-xlib:
- EGL/Open GL backend for X11.
+ --disable-tests
+ Disable building the Clutter tests suite.
- wayland:
- EGL/Open GL backend for Wayland. (EXPERIMENTAL)
+ --disable-examples
+ Disable building the Clutter API reference examples.
- eglx:
- EGL/Open GL|ES backend for X11.
+ --enable-deprecated=[yes/no]
+ Whether deprecated symbols should be available when compiling Clutter.
- eglnative:
- EGL/Open GL|ES backend on 'native windowing system' - i.e
- raw framebuffer. Expects the EGL implementation to provide
- a createNativeWindow() call.
+ --disable-Bsymbolic
+ Disable linking with -Bsymbolic.
- cex100:
- EGL/Open GL|ES backend on Intel CE3100 and CE4100 platforms.
- Requires libgdl.
+ --enable-x11-backend=[yes/no/check]
+ Enable the X11 backend. (default=check)
- osx:
- OS X backend. (EXPERIMENTAL)
+ --enable-win32-backend=[yes/no/check]
+ Enable the native Microsoft Windows backend. (default=check)
- win32:
- Microsoft Windows(tm) WGL backend.
+ --enable-quartz-backend=[yes/no/check]
+ Enable the native Quartz backend. (default=check)
- fruity:
- Apple iPod Touch(tm)/iPhone(tm) backend. (EXPERIMENTAL)
+ --enable-gdk-backend=[yes/no/check]
+ Enable the GDK backend. (default=check)
- --with-imagebackend=[gdk-pixbuf/quartz/internal]
- Select the image loading backend used by COGL
+ --enable-wayland-backend=[yes/no]
+ Enable the Wayland client backend. (default=no) [EXPERIMENTAL]
- gdk-pixbuf:
- Depend on gdk-pixbuf-2.0 (default for the glx, eglx,
- eglnative, win32 flavours and recommended).
+ --enable-cex100-backend=[yes/no]
+ Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]
- quartz:
- Depend on CoreGraphics (default for the osx flavour).
+ --enable-egl-backend=[yes/no]
+ Enable the EGL framebuffer backend. (default=no)
- internal:
- Internal JPEG and PNG loader. Should only be used
- for testing on new platforms
+ --enable-tslib-input=[yes/no]
+ Enable the TSLib input backend. (default=no) [EXPERIMENTAL]
- --with-gles=[1.1/2.0]
- Select the GLES version (for EGL backends) (default=1.1)
+ --enable-evdev-input=[yes/no]
+ Enable the evdev input backend. (default=no) [EXPERIMENTAL]
See also the INSTALL file generated by autotools for further information.
Bugs should be reported to the Clutter Bugzilla at:
- http://bugzilla.clutter-project.org/enter_bug.cgi?product=clutter
+ http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
You will need a Bugzilla account.
• what system you're running Clutter on;
• which version of Clutter you are using;
- • which version of GLib and OpenGL (or OpenGL ES) 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.
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:
+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
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
-------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------