build: Generate README

Use the configure script to generate the README from a template file, so
that we can keep the versions of the dependencies in one place.

1 files changed, 1058 insertions, 0 deletions

diff --git a/README.in b/README.in
new file mode 100644
index 000000000..25524aceb
--- /dev/null
+++ b/README.in
@@ -0,0 +1,1058 @@
+README for Clutter @CLUTTER_VERSION@
+===============================================================================
+
+Clutter is an open source software library for creating fast, compellin,
+portable, and dynamic graphical user interfaces.
+
+REQUIREMENTS
+-------------------------------------------------------------------------------
+
+Clutter currently requires:
+
+  • GLib ≥ @GLIB_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:
+
+  • GDK-Pixbuf ≥ @GDK_PIXBUF_REQ_VERSION@
+
+On X11, Clutter depends on the following extensions
+
+  • XComposite ≥ 0.4
+  • XDamage
+  • XExt
+  • XFixes ≥ 3
+  • 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:
+
+  http://www.khronos.org
+
+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 reference for the latest stable release and unstable developers
+snapshot are available at:
+
+   http://docs.clutter-project.org/docs/clutter/stable/
+   http://docs.clutter-project.org/docs/clutter/unstable/
+
+New releases of Clutter are available at:
+
+   http://source.clutter-project.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.clutter-project.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-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).
+
+ --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.
+
+ --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.
+
+        wayland:
+                EGL/Open GL backend for Wayland. (EXPERIMENTAL)
+
+	eglx:
+                EGL/Open GL|ES backend for X11.
+
+	eglnative:
+                EGL/Open GL|ES backend on 'native windowing system' - i.e
+		raw framebuffer. Expects the EGL implementation to provide
+                a createNativeWindow() call.
+
+        cex100:
+                EGL/Open GL|ES backend on Intel CE3100 and CE4100 platforms.
+                Requires libgdl.
+
+        osx:
+                OS X backend. (EXPERIMENTAL)
+
+        win32:
+                Microsoft Windows(tm) WGL backend.
+
+        fruity:
+                Apple iPod Touch(tm)/iPhone(tm) backend. (EXPERIMENTAL)
+
+ --with-imagebackend=[gdk-pixbuf/quartz/internal]
+        Select the image loading backend used by COGL
+
+        gdk-pixbuf:
+                Depend on gdk-pixbuf-2.0 (default for the glx, eglx,
+                eglnative, win32 flavours and recommended).
+
+        quartz:
+                Depend on CoreGraphics (default for the osx flavour).
+
+        internal:
+                Internal JPEG and PNG loader. Should only be used
+                for testing on new platforms
+
+ --with-gles=[1.1/2.0]
+        Select the GLES version (for EGL backends) (default=1.1)
+
+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.clutter-project.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 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/
+
+RELEASE NOTES
+-------------------------------------------------------------------------------
+
+Relevant information for developers with existing Clutter applications
+wanting to port to newer releases (see NEWS for general information on new
+features).
+
+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_upload_data has been split into two new and
+    more functional versions; clutter_texture_set_from_rgb_data(),
+    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.
+
+* The priority of the various users of the GLib main loop has been
+  reviewed and changed were necessary. Every paint is queued with a
+  priority of G_PRIORITY_DEFAULT + 10; timelines are allocated with
+  a G_PRIORITY_DEFAULT + 30 priority; events are processed with a
+  G_PRIORITY_DEFAULT priority. This ensures that events are processed
+  before the paints take place.
+
+* The ClutterActor::allocate_coords() has been renamed to
+  ClutterActor::query_coords(), in order to clarify its usage.
+
+* Actors overriding ClutterActor::request_coords() and
+  ClutterActor::query_coords() must convert sizes obtained from the
+  public API from pixels to ClutterUnits, using the conversion
+  macros found in clutter-units.h. The conversion will be necessary
+  until the public API will switch over to returning the generic
+  units too.
+
+* Users of Intel video cards should find that disabling sync-to-vblank
+  is no longer necessary. In case Clutter applications take really
+  long times for redrawing and appear stuck and unresponsive, the
+  sync-to-vblank feature might still be the culprit; in that case, use
+  "export CLUTTER_VBLANK=none" to disable it and file a bug reporting the
+  video card model, the driver version and the X server version.
+
+* ClutterTimeline objects now share the same timeout pool (see the
+  ClutterTimeoutPool API). This might cause problems with heavily
+  threaded libraries without integration with the GLib main loop.
+  If an application experiences bad behaviours during animations
+  use "export CLUTTER_TIMELINE=no-pool" to disable the timeout pool.
+
+* 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
+  tests/ directory.
+
+* The ClutterEvent API has been changed, and specific functions have been
+  removed in favour of event-agnostic ones.
+
+* 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.
+
+* Runtime options now dependant on backend.
+
+* 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.