README for Clutter @CLUTTER_VERSION@

===============================================================================

Clutter is an open source software library for creating fast, compelling,

portable, and dynamic graphical user interfaces.

REQUIREMENTS

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

Clutter currently requires:

  • GLib ≥ @GLIB_REQ_VERSION@

  • Cogl ≥ @COGL_REQ_VERSION@

  • JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@

  • Atk ≥ @ATK_REQ_VERSION@

  • Cairo ≥ @CAIRO_REQ_VERSION@

  • PangoCairo ≥ @PANGO_REQ_VERSION@

When building the X11 backend, Clutter depends on the following extensions:

  • XComposite ≥ @XCOMPOSITE_REQ_VERSION@

  • XDamage

  • XExt

  • XInput (1.x or 2.x)

  • XKB

When building the Wayland backend, Clutter also depends on:

  • wayland-client

  • xkbcommon

When building the GDK backend, Clutter also depends on:

  • gdk-3.0 > @GDK_REQ_VERSION@

When building the CEx100 backend, Clutter also depends on:

  • libgdl

When building the evdev input backend, Clutter also depends on:

  • xkbcommon

  • libudev ≥ @LIBUDEV_REQ_VERSION@

  • libinput ≥ @LIBINPUT_REQ_VERSION@

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

RESOURCES

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

The official Clutter website is:

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

The API references for the latest stable release are available at:

   https://developer.gnome.org/clutter/stable/

   https://developer.gnome.org/cogl/stable/

The Clutter Cookbook is available at:

   https://developer.gnome.org/clutter-cookbook/

New releases of Clutter are available at:

   https://download.gnome.org/sources/clutter/

The Clutter blog is available at:

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

To subscribe to the Clutter mailing list and read the archives, use the

Mailman web interface available at:

   https://mail.gnome.org/mailman/listinfo/clutter-list

New bug page on Bugzilla:

   https://bugzilla.gnome.org/enter_bug.cgi?product=clutter

Clutter is licensed under the terms of the GNU Lesser General Public

License, version 2.1 or (at your option) later.

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:

  https://wiki.gnome.org/Projects/Clutter

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-maintainer-flags=[no/yes/error]

        Use strict compiler flags. This defaults to 'yes' for building from

        Git to 'no' for tarball releases. If 'error' is used, then -Werror

        will be enabled (if available).

 --enable-gtk-doc

	use gtk-doc to build API documentation (default=no). Requires gtk-doc

	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.

 --disable-tests

        Disable building the Clutter tests suite.

 --disable-examples

        Disable building the Clutter API reference examples.

 --enable-deprecated=[yes/no]

        Whether deprecated symbols should be available when compiling Clutter.

 --disable-Bsymbolic

        Disable linking with -Bsymbolic.

 --enable-x11-backend=[yes/no/check]

        Enable the X11 backend. (default=check)

 --enable-win32-backend=[yes/no/check]

        Enable the native Microsoft Windows backend. (default=check)

 --enable-quartz-backend=[yes/no/check]

        Enable the native Quartz backend. (default=check)

 --enable-gdk-backend=[yes/no/check]

        Enable the GDK backend. (default=check)

 --enable-wayland-backend=[yes/no]

        Enable the Wayland client backend. (default=no) [EXPERIMENTAL]

 --enable-cex100-backend=[yes/no]

        Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]

 --enable-egl-backend=[yes/no]

        Enable the EGL framebuffer backend. (default=no)

 --enable-tslib-input=[yes/no]

        Enable the TSLib input backend. (default=no) [EXPERIMENTAL]

 --enable-evdev-input=[yes/no]

        Enable the evdev input backend. (default=no) [EXPERIMENTAL]

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.gnome.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, Cogl, and OpenGL (or OpenGL ES) you are using;

  • which video card and which drivers you are using, including output of

    glxinfo and xdpyinfo (if applicable);

  • how to reproduce the bug.

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/

Patches submitted against Clutter have to pass the conformance test suite, or,

if possible, add new unit tests for the conformance test suite in case of new

features. Ensure you run the conformance test suite every for every patch you

wish to submit, by using:

  make -C tests/conform check

and verifying that the whole test suite passes.

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

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

• The evdev backend specific ClutterPointerConstrainCallback type was changed

  to include not only the target position but also the previous position. This

  is an API change, and will require a version check in any caller code.

Release Notes for Clutter 1.24

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

• ClutterModel, ClutterModelIter, and ClutterListStore have been deprecated.

  You're strongly encouraged to use the GListModel interface, and the

  GListStore class, as a replacement.

• The macros used to access the state flags in ClutterActor have been

  deprecated, and replaced by equivalent functions.

• Clutter types now can be used with the `g_autoptr()` and `g_auto()`

  macros provided by GLib and supported by GCC and Clang.

• The old, non-namespaced CLUTTER_* key symbols now have an associated

  deprecation warning.

• The private, unused ClutterX11XInputEventTypes enumeration, which was

  erroneously placed in the clutter-x11.h public header, has been removed.

• The Wayland client backend is now autodetected depending on whether the

  required dependencies are available.

Release Notes for Clutter 1.22

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

• The default backend for Clutter starting from this release is the GDK

  backend, if Clutter was compiled with it. This allows better integration

  with the underlying windowing system platform on X11 and Wayland. On

  Windows and MacOS the native backends are still the preferred ones. If you

  require a specific backend you should use clutter_set_windowing_backend()

  with the CLUTTER_WINDOWING_* backend you require, prior to call

  clutter_init().

• The ClutterRequestMode enumeration has a new value. Code checking for the

  values of ClutterRequestMode should already be resilient to changes to this

  enumerations, like for all enumerations in Clutter.

Release Notes for Clutter 1.20

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

• The clutter_stage_set_paint_callback() experimental function has been

  removed from the Clutter ABI; it has been replaced by the ::after-paint

  signal on the ClutterStage class. The set_paint_callback() method was

  marked as "experimental", required a special definition to be usable, and

  no guarantees were made on its continued existence.

Release Notes for Clutter 1.18

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

• Until 1.18, ClutterStage removed its children during its dispose()

  implementation, before the default ClutterActor::destroy() implementation

  would run. ClutterStage will now destroy the children when it is destroyed

  to ensure that the children are destroyed, and that custom code can remove

  references through the ClutterActor::destroy signal.

• Clutter does not depend on the XFIXES extension API on X11 any more. Before

  1.18 Clutter used the XFIXES API to hide the cursor; the API is less than

  useful for toolkits and applications, so Clutter unconditionally uses the

  fall back code that was in place in case XFIXES was not available.

• ClutterText emits the ::insert-text and ::delete-text signals before the

  contents of the ClutterTextBuffer are changed, as documented. The signal

  emission cannot be guaranteed if the ClutterTextBuffer API is used instead

  of the ClutterText API.

• Starting from 1.18, the Clutter evdev input device backend no longer uses

  libevdev and libgudev directly, but relies on libinput for discovering,

  reading and processing input devices.

• The Clutter evdev input device backend was already considered

  experimental and not subject to Clutter's API and ABI stabitility

  guarantees. Starting from 1.18, users have to explicitly acknowldge

  this by having to #define CLUTTER_ENABLE_COMPOSITOR_API to use its

  public API.

Release Notes for Clutter 1.16

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

• Implicit transitions will not be created on actors that are not mapped,

  unless they are in a cloned branch of the scene graph. This was never an

  approved case, as ClutterActor would implicitly skip layout and paint on

  unmapped actors, but now it's being enforced through the animation machinery

  as well. Using explicit transitions still works, as explicit transitions

  completely place the developer in charge.

Release Notes for Clutter 1.14

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

• The X11 backend (both core X events and XInput 2 backends) now mask out

  scroll lock and num lock modifiers from the event state.

Release Notes for Clutter 1.12

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

• ClutterBinLayout no longer requests or allocates size for children that are

  not visible, which is how the other layout managers work.

• The expansion and alignment layout properties in all the layout managers

  that provide them have been deprecated in favour of the equivalent ones

  on ClutterActor; the ClutterLayoutManager implementations provided by

  Clutter have been updated to honour the ClutterActor:x-expand,

  ClutterActor:y-expand, ClutterActor:x-align, and ClutterActor:y-align

  properties, if set.

• Setting the ClutterActor:fixed-position-set to FALSE will reset any

  currently set fixed position to (0, 0).

• ClutterActor's margin properties are now animatable.

• ClutterBindingActionFunc typedef now has a user_data parameter; the user

  data was passed by every caller, and ClutterBindingActionFunc was not used

  anywhere in the API except for documentation purposes.

• The clutter_threads_enter() and clutter_threads_leave() functions have been

  deprecated; the lead to non portable code, and encourage broken behaviour

  with regards to threaded applications. The only supported, portable way of

  writing Clutter application employing threads is to defer long running

  operations to a worker thread, and schedule UI updates to the main loop at

  well defined synchronization points.

Release Notes for Clutter 1.10

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

• The ClutterActor::paint, ClutterActor::queue-redraw, and

  ClutterActor::queue-relayout signals are now annotated as not allowing

  signal emission hooks; this enables some optimization inside GLib, and

  given the amount of emissions these three signals have, we want to get

  through all the fast paths we can.

• The ClutterActorBox parameter of the ClutterActor::allocation-changed

  signal is now marked as G_SIGNAL_TYPE_STATIC_SCOPE.

• The clutter-stage-window.h header is not installed any more; this header

  was never meant to be public in the first place, and nothing could have

  been implementing the ClutterStageWindow interface and use it with Clutter.

• ClutterActor will call its unmap() implementation when it is removed from

  its parent. This may happen after the ClutterActor::destroy signal has been

  emitted, i.e. during its dispose(). Prior to 1.10, calling the

  clutter_actor_destroy() function would unmap the actor first, and then

  emit the destroy signal. This means that extra care should be used when

  overriding the map() and unmap() virtual functions, to avoid dereferencing

  NULL pointers. It is also worthy of note that since Clutter 1.8, overriding

  map() or unmap() is not required any more for subclasses of ClutterActor

  that have children, as ClutterActor will automatically do the right thing

  inside its own implementation, and map or unmap its children when needed.

• ClutterBox and ClutterGroup have been deprecated. ClutterActor should be

  used directly, instead. Since ClutterStage inherits from ClutterGroup, the

  instance and class structures are still available, but subclassing Group

  is strongly disencouraged.

• ClutterContainer provides default implementations for add(), remove(),

  foreach(), raise(), lower(), and sort_depth_order(); this means that

  overriding these virtual functions is now deprecated, and developers

  should only implement ClutterContainer for classes providing child

  properties.

• ClutterActor is not an abstract type any more, and can be instantiated

  either through clutter_actor_new() or through g_object_new().

• ClutterActor now implements ClutterContainer, and takes over the entire API

  for modifying the scene graph; this means that every actor can have children

  and it's not necessary any more to implement the ClutterContainer interface.

  ClutterActor provides new API to replace clutter_actor_set_parent() and

  clutter_actor_unparent(), as well as a default implementation of every

  Container virtual function. Existing actors overriding ClutterContainer and

  providing an alternate implementation will continue to work, even though it

  is strongly encouraged to port to the new API.

• The ClutterActor::destroy signal is going to be emitted at the beginning

  of the dispose sequence of a ClutterActor, instead of the end. This allows

  to access the state of the actor being destroyed, instead of just being

  able to use its pointer. This may expose bugs in code that does not check

  for NULL actor pointers.

• The long since broken depth cueing support in ClutterStage has been

  deprecated; the fixed pipeline fog API has been pretty much useless

  since the switch to colors and textures with premultiplied alpha

  channels. Setting ClutterStage:use-fog to TRUE has no visible results,

  and querying the :use-fog and :fog properties will always yield the

  default values.

• ClutterDeformEffect switched from using CoglVertexBuffer to using the

  CoglPrimitive API internally, to improve performance and use non-deprecated

  Cogl API. CoglPrimitive converts COGL_WRAP_MODE_AUTOMATIC to

  COGL_WRAP_MODE_CLAMP_TO_EDGE, unlike CoglVertexBuffer which converts it to

  COGL_WRAP_MODE_REPEAT. This prevents artifacts when sampling texture

  coordinates outside the [ 0, 1 ] range. This change may cause the back

  texture to not be painted if its coordinates go outside the allowed range,

  for instance when using a custom transformation matrix on the back material

  used by the ClutterDeformEffect.

• The "default stage" has been deprecated; since the 1.0 release, the default

  stage creation was deferred to the call to clutter_stage_get_default(), and

  the preferred way for getting a ClutterStage was calling clutter_stage_new()

  instead. On platforms that do not support multiple stages, attempting to

  create more than one stage will lead to an error, and Clutter will abort.

• Clutter can support multiple backends in the same shared library. Only one

  windowing or input backend can be used at run time. As a result of this

  change, the shared library name used by Clutter has changed from:

        libclutter-<flavour>-<API version>.so

  to:

        libclutter-<API version>.so

  The pkg-config file has been updated accordingly. Until the next major API

  break, Clutter will ship compatibility links for all the previous "flavours"

  that were available in versions < 1.10; this allows applications dynamically

  linking against Clutter, or using dlopen(), to keep working. For libraries

  and applications dynamically linking against Clutter, though, it is still

  recommended to recompile to make sure that the most recent version is being

  used. Language bindings using GObject Introspection will automatically use

  the new shared library without requiring any change.

• The windowing system backend for the CE3100 and CE4100 platforms using the

  libgdl library is now implemented as a separate backend instance, instead

  of being a sub-flavour of the EGL native framebuffer backend. This change

  introduces a new header file, under $includedir/clutter-1.0/clutter/cex100,

  which should be included to access the CEx100-specific API. The API and

  ABI of the platform API has not been changed, though it should still be

  considered experimental.

• As of 1.10 it is not necessary any more to call clutter_threads_init() to

  initialize threading support in Clutter; after the changes in GLib 2.32,

  threading support in Clutter is always enabled. The rules on how to use

  Clutter from multiple threads haven't changed.

• Deprecated API is now marked using the CLUTTER_DEPRECATED and the

  CLUTTER_DEPRECATED_FOR annotations; these two annotations will result in

  compiler warnings when attempting to use the deprecated API. It is possible

  to disable deprecation warnings for Clutter by defining the

  CLUTTER_DISABLE_DEPRECATION_WARNINGS symbol when compiling. The previous

  deprecation symbol, CLUTTER_DISABLE_DEPRECATED, is only used for macros.

• Deprecated functionality has been moved to separate header files, installed

  under the $includedir/clutter-1.0/clutter/deprecated directory. These files

  are still included by default by clutter/clutter.h.

Release Notes for Clutter 1.8

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

• Cogl has been split out of tree. Clutter depends on Cogl, so users should

  not notice anything. Developers using pkg-config will gain an extra Cogl

  dependency.

• The clutter_actor_get_gid() and clutter_get_actor_by_gid() functions have

  been deprecated. They should not have been public in the first place.

• ClutterShader and its relative API have been deprecated. ClutterShaderEffect

  and the effect API is the proper way to use GLSL shaders with ClutterActors.

  It is possible to instantiate a ClutterShaderEffect directly.

• ClutterText's paint volume has been implemented using the ink rectangle of

  the PangoLayout used to paint, to allow culling to work properly even in

  the case of glyphs spilling outside the logical rectangle.

• Non fully opaque children of a non fully opaque actor will be composited

  in an offscreen framebuffer object to preserve the correct overall opacity.

  This changes the way non fully opaque actors are drawn, and might cause

  some code relying on the old, unspecified behaviour to produce different

  results.

• ClutterBoxLayout layout algorithm has been changed to map the more mature

  and more stable GtkBox one.

• The ClutterText:editable property was incorrectly defined in the GParamSpec

  as being TRUE by default, but it was initialized to FALSE. To avoid breaking

  existing code, the default value inside the GParamSpec (and inside the

  documentation) has been changed to FALSE as well.

• The preferred way to draw inside a ClutterCairoTexture is connecting to

  its ::draw signal, and calling the invalidate() method. The old pattern

  of creating the Cairo context using the create() method is deprecated but

  still working as intended.

• ClutterScore has been deprecated; the preferred way to chain up multiple

  animations is to use the ClutterAnimator or ClutterState classes.

Release Notes for Clutter 1.6

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

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