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.

* 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           