mutter/README

Clutter README.
===============

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.

Its not meant to be a full featured GUI toolkit for regular desktop
apps nor provide a general interface to *all* OpenGL functionality.

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

RELEASE NOTES
====

Relevant information for developers with existing Clutter applications
wanting to port to newer releases;

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.

* 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

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.

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.

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.