Clutter - README
===============================================================================

Clutter is an open source software library for creating portable, fast,
visually rich and animated graphical user interfaces.

Clutter currently requires:

  • GLib >= 2.16.0
  • Cairo >= 1.6
  • PangoCairo >= 1.20
  • OpenGL >= 1.3 or 1.2+multitexturing, OpenGL ES 1.1 or OpenGL ES 2.0
  • GLX, SDL, WGL or an EGL Implementation
  • JSON-GLib >= 0.8 (optional)
  • GDK-Pixbuf >= 2.0 (optional)

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 >= 1.11

If you are building the Introspection data you will also need:

  • GObject-Introspection >= 0.6.4

If you want built in support for profiling Clutter you will also need:

  • UProf >= 0.2

UProf is available from:

  git://git.moblin.org/uprof.git

-------------------------------------------------------------------------------

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://www.clutter-project.org/docs/clutter/stable/
   http://www.clutter-project.org/docs/clutter/unstable/

New releases of Clutter are available at:

   http://www.clutter-project.org/sources/clutter/

The Clutter blog is at:

   http://www.clutter-project.org/blog/

To subscribe to the Clutter mailing list, send an email 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 licensed under the terms of the GNU Lesser General Public
License, version 2.1 or (at your option) later.

BUILDING AND INSTALLATION
===============================================================================

See the INSTALL file.

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]
        Use strict compiler flags. This defaults to 'yes' for developers
        snapshots and to 'no' for stable releases.

 --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.

 --with-flavour=[glx/eglx/eglnative/osx/win32/fruity]
        Select the Clutter backend: (default=glx)

	glx:
                Fully featured GLX backend. Using Open GL.

	eglx:
                EGL/Open GL ES backend for EGL on X windows implementations

	eglnative:
                EGL/Open GL ES backend on 'native windowing system' - i.e
		raw framebuffer. Expects the EGL implementation to provide
                a createNativeWindow() call. Also it optionally supports
		tslib for touchscreen events.

        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)

 --with-json=[internal/check/system]
        Select the JSON-GLib copy to use (default=check)

        internal:
                Use the internal copy of JSON-GLib for ClutterScript

        check:
                Check for the existence of a system copy of JSON-GLib
                and if it is available, make Clutter depend on it

        system:
                Only use the system copy of JSON-GLib and warn if not found

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 contained TODO file for
pending tasks, 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.

BUGS
===============================================================================

Bugs should be reported to the Clutter Bugzilla at:

  http://bugzilla.o-hand.com/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.

When attaching a patch to Bugzilla you should also toggle the
'copyright-waived' attachment flag, after reading the Copyright Waiver notice
here:

  http://bugzilla.openedhand.com/waiver.html

If you do not intend to waive your copyright you should contact the Clutter
development team to arrange a suitable solution.

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.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.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   