12363448c7
* README:
Sync up/improve ready for 0.8 release.
* AUTHORS:
Sync up to date - hope I havn't missed anyone..
516 lines
21 KiB
Text
516 lines
21 KiB
Text
Clutter 0.8 README.
|
|
===================
|
|
|
|
Clutter it an open source software library for creating fast, visually
|
|
rich and animated graphical user interfaces.
|
|
|
|
Clutter currently requires:
|
|
|
|
* GLib >= 2.14.0
|
|
* PangoCairo >= 1.18
|
|
* OpenGL >= 1.4, OpenGL ES 1.1 or OpenGL ES 2.0
|
|
* GLX, SDL, WGL or an EGL Implementation
|
|
|
|
The official website is:
|
|
http://www.clutter-project.org
|
|
The Clutter blog is at
|
|
http://www.clutter-project.org/blog
|
|
To subscribe to the Clutter mailing list, send mail to:
|
|
clutter+subscribe@o-hand.com
|
|
The official mailing list archive is:
|
|
http://lists.o-hand.com/clutter/
|
|
New bug page on Bugzilla:
|
|
http://bugzilla.o-hand.com/enter_bug.cgi?product=Clutter
|
|
|
|
Clutter is licensed under the terms of the GNU Lesser General Public
|
|
License, version 2.1 or (at your option) later.
|
|
|
|
INSTALLATION
|
|
============
|
|
|
|
See the INSTALL file. Info on specific Clutter options;
|
|
|
|
--enable-debug=[no/minimum/yes]
|
|
Turn on debugging (default=yes):
|
|
yes: All glib asserts, checks and runtime clutter verbose messages.
|
|
minimum: Just glib cast checks and runtime clutter verbose messagaes.
|
|
no: No glib asserts or checks and no runtime clutter verbose messages
|
|
(Only really of use in extreme performance cases)
|
|
|
|
--enable-maintainer-flags=[no/yes]
|
|
Use strict compiler flags (default=no)
|
|
|
|
--enable-gtk-doc
|
|
use gtk-doc to build API documentation (default=no). Requires gtk-doc
|
|
present on system
|
|
|
|
--enable-manual=[no/yes]
|
|
Build application developers manual. Requires jw and xmlto binaries.
|
|
Presently incomplete.
|
|
|
|
--without-fpu
|
|
Assume target hardware has no floating point unit. Useful only
|
|
for embedded targets such as ARM.
|
|
|
|
--with-flavour=[glx/eglx/eglnative/sdl/osx/win32]
|
|
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.
|
|
|
|
sdl: Basic SDL backend, using Open GL. Should provide portability
|
|
to Windows and possibly other OS's.
|
|
|
|
osx: OS X backend. (experimental)
|
|
|
|
win32:
|
|
Microsoft Windows(tm) WGL backend (experimental)
|
|
|
|
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, sdl, 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]
|
|
Select the JSON-GLib copy to use (default=internal)
|
|
|
|
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
|
|
|
|
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 Minor versions break both API and ABI but are parallel
|
|
installable. The same Minor version with differing Micro version is
|
|
expected to be ABI compatible with other micro versions. Though this
|
|
is not guarenteed, especially for odd numbered minor releases, we'll
|
|
try our very hardest (promise).
|
|
|
|
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 SVN repository.
|
|
|
|
HACKING
|
|
=======
|
|
|
|
If you want to hack on and improve Clutter, check the contained TODO
|
|
file for pending tasks, and HACKING for general coding guidelines.
|
|
|
|
BUGS
|
|
====
|
|
|
|
Bugs should be reported to the OpenedHand Bugzilla at:
|
|
|
|
http://bugzilla.o-hand.com/enter_bug.cgi?product=Clutter
|
|
|
|
You will need an account.
|
|
|
|
In the report you should include:
|
|
* what system you're running Clutter on;
|
|
* which version of Clutter you are using;
|
|
* which version of GLib and OpenGL you are using;
|
|
* which video card and which drivers you are using, including output of
|
|
glxinfo and xdpyinfo;
|
|
* how to reproduce the bug.
|
|
|
|
If you cannot reproduce the bug with one of the tests that come with Clutter
|
|
source code, you should include a small test case displaying the bad
|
|
behaviour.
|
|
|
|
If the bug exposes a crash, the exact text printed out and a stack trace
|
|
obtained using gdb are greatly appreciated.
|
|
|
|
|
|
PATCHES
|
|
=======
|
|
|
|
Patches should be submitted using Bugzilla. Patches fixing a bug should be
|
|
attached to the bug report; patches for new features or for fixing bugs not
|
|
yet reported should be attached to a newly opened bug. Patches should always
|
|
be in the unified diff format, using:
|
|
|
|
diff -Nuarp clutter.source clutter.patched > clutter-patch.diff
|
|
|
|
If diffing against the SVN repository, you should use:
|
|
|
|
svn diff --diff-cmd=diff -x -Nuarp > clutter-patch.diff
|
|
|
|
|
|
RELEASE NOTES
|
|
=============
|
|
|
|
Relevant information for developers with existing Clutter applications
|
|
wanting to port to newer releases (See NEWS for general new feature info).
|
|
|
|
Release Notes for Clutter 0.8
|
|
-------------------------------
|
|
|
|
* The COGL GL wrapper API has been completely overhauled and now
|
|
contains many new features including new greatly improved texture
|
|
abstractions (slicing, mipmapping, deformations etc, greatly
|
|
simplifying ClutterTexture), image loading and abstraction, path
|
|
based primitive drawing, clipping, and improved FBO and shader
|
|
support. It is now also fully documented.
|
|
|
|
GL Texture Rectangle ext is no longer used, the regular 2D NPOTS
|
|
extension is preffered instead but not required.
|
|
|
|
* Clutter now has basic suppport for multiple input devices assuming
|
|
the backend supports it (currently X11 based via XInput and Fruity
|
|
backends). New API supporting this includes
|
|
clutter_event_get_device_id, clutter_get_input_device_for_id,
|
|
clutter_grab_pointer_for_device & clutter_ungrab_pointer_for_device.
|
|
|
|
XInput support needs to be explicitly enabled at runtime by calling
|
|
clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput ()
|
|
can then be called after to check if XInput extension present and use-able.
|
|
|
|
* The functions that return the transformed position of an actor have
|
|
been renamed to be more explicit about it:
|
|
|
|
clutter_actor_get_abs_position - clutter_actor_get_transformed_position
|
|
clutter_actor_get_abs_size - clutter_actor_get_transformed_size
|
|
|
|
Their behaviour has not been changed.
|
|
|
|
* To increase portability, Clutter does not strictly depend on
|
|
GdkPixbuf anymore; this means that you will have to include
|
|
<gdk-pixbuf/gdk-pixbuf.h> yourself if you are operating with
|
|
GdkPixbuf objects and not including that header. The GdkPixbuf-based
|
|
API has been removed from Clutter core:
|
|
|
|
clutter_texture_new_from_pixbuf
|
|
clutter_texture_set_pixbuf
|
|
clutter_texture_get_pixbuf
|
|
|
|
are all deprecated functions. It is still possible to load a GdkPixbuf
|
|
into a ClutterTexture with this sample code:
|
|
|
|
clutter_texture_set_from_rgb_data (texture,
|
|
gdk_pixbuf_get_pixels (pixbuf),
|
|
gdk_pixbuf_get_has_alpha (pixbuf),
|
|
gdk_pixbuf_get_width (pixbuf),
|
|
gdk_pixbuf_get_height (pixbuf),
|
|
gdk_pixbuf_get_rowstride (pixbuf),
|
|
4, 0,
|
|
&error);
|
|
|
|
ClutterTexture also now has a new filename property and
|
|
clutter_texture_new_from_file which is intended as an alternate to
|
|
common previous GdkPixbuf primary usage (i.e loading images from
|
|
disk).
|
|
|
|
To read texture data back into a pixbuf or system memory use a combination
|
|
of clutter_texture_get_cogl_texture & cogl_texture_get_data.
|
|
|
|
The clutter-gtk integration library has API for using GdkPixbuf with
|
|
ClutterTextures (among others).
|
|
|
|
ClutterTexture now supports a keep-aspect property which is set to FALSE
|
|
by default.
|
|
|
|
* clutter_texture_from_actor will now reparent source actors if they
|
|
are not parented. This behaviour may change in future releases.
|
|
There are known not yet fixed issues with source actors that set
|
|
depth or use clipping.
|
|
|
|
* The size negotiation API has been completely changed in order to allow
|
|
the creation of non-fixed layout managers. These functions have been
|
|
removed:
|
|
|
|
clutter_actor_request_coords()
|
|
clutter_actor_query_coords()
|
|
|
|
from the ClutterActor API, as well as their virtual functions inside
|
|
the ClutterActorClass. The size of an actor is now split into two
|
|
different concepts: the preferred size (width and height
|
|
separatedly) and the size that has been allocated by the container
|
|
to which that actor belongs. Clutter still defaults to the fixed
|
|
layout management (i.e ClutterGroup) of the actors, but supports
|
|
fluid layout managers written using the new API.
|
|
|
|
Composite actors (actors with 'private' children not implementing the
|
|
container interface) now need to implement an allocate method here pass
|
|
an allocation to any composite children.
|
|
|
|
* Clutter now depends on PangoCairo for the font rendering. The PangoClutter
|
|
API is still considered semi-private and no guarantees are made on its
|
|
stability.
|
|
|
|
* ClutterShader API has been slightly changed: the ClutterStage:bound
|
|
property, clutter_shader_bind() and clutter_shader_is_bound() have
|
|
been renamed to :compiled, clutter_shader_compile() and
|
|
clutter_shader_is_compiled(), respectively. The previously semi-private
|
|
clutter_shader_release_all() function is now not exported anymore.
|
|
|
|
* ClutterStage is not an abstract type anymore: it can be instantiated
|
|
using clutter_stage_new() and it can be properly subclassed. If the
|
|
backend supports multiple stages, every stage will be a new window,
|
|
whose lifetime will have to be managed by the developer. Clutter will
|
|
still create the default stage, and guarantees that every call to
|
|
clutter_stage_get_default() will return exactly the same pointer.
|
|
|
|
* Actors now have a new 'show-on-set-parent' property set to TRUE by
|
|
default. With this property set to TRUE, actors will automatically
|
|
have clutter_actor_show() called on them when a parent is set (i.e
|
|
added to a container).
|
|
|
|
* Clutter now features support for multiple stages assuming supported
|
|
by the backend. See test-multistage.c for example of usage. This
|
|
does not change the automatic creation of the default stage.
|
|
A single GL context is used across all stages meaning GL resources
|
|
are shared.
|
|
|
|
* There is now an experimental native iPod Touch/iPhone UIKit backend
|
|
named 'fruity'.
|
|
|
|
* There is now an experimental native Win32 WGL backend.
|
|
|
|
* COGL (and therefor Clutter) now optionally features initial support for
|
|
OpenGL ES 2.0. It features support for shaders.
|
|
|
|
* Some more focused timeline unit tests have been added and some tweaks to
|
|
timeline semantics were made; E.g. For a 10 frame timeline here are some
|
|
points about the semantics:
|
|
- When you create a timeline it starts with current_frame_num == 0
|
|
- After starting a timeline, the first timeout is for current_frame_num == 1
|
|
(Notably it isn't 0 since there is a delay before the first timeout signals
|
|
so re-asserting the starting frame (0) wouldn't make sense.)
|
|
- For a non looping timeline the last timeout would be for
|
|
current_frame_num == 10
|
|
- For a looping timeline the timeout for current_frame_num == 10 would be
|
|
followed by a timeout for current_frame_num == 1 and frame 0 is considered
|
|
== frame 10.
|
|
- Asking for a timeline of N frames might better be described as asking for
|
|
a timeline of _length_ N.
|
|
|
|
* The behaviour of clutter_actor_get_opacity() has been slightly changed;
|
|
instead of returning the composited opacity of the entire parents chain
|
|
of an actor, clutter_actor_get_opacity() does what you mean, and returns
|
|
the opacity set with clutter_actor_set_opacity(). The composited
|
|
opacity value is now returned by clutter_actor_get_paint_opacity().
|
|
|
|
* Until 0.6, clutter_label_get_color() would have returned a ClutterColor
|
|
with the alpha component equal to the composited opacity of the label.
|
|
Now, clutter_label_get_color() returns a copy of the exact color set
|
|
with clutter_label_set_color().
|
|
|
|
* The ClutterEntry actor will automatically handle key events inside
|
|
a key-press-event handler. This deprecates the usage of
|
|
clutter_entry_handle_key_event() to update the contents of the
|
|
entry using the ClutterKeyEvent.
|
|
|
|
* The Clutter X11 and GLX backends feature support for wrapping external
|
|
X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX
|
|
extension if available and fallback to slower XGetImage copys if not.
|
|
|
|
* ClutterContainer can have per child custom propertys via ClutterChildMeta.
|
|
|
|
Release Notes for Clutter 0.6
|
|
-------------------------------
|
|
|
|
* Now that every actor has events, the class signal handlers have been
|
|
removed from ClutterStageClass and moved into ClutterActorClass.
|
|
|
|
* The CLUTTER_2BUTTON_PRESS and CLUTTER_3BUTTON_PRESS event types have been
|
|
removed in favour of the ClutterButtonEvent:click_count counter
|
|
|
|
* X11 related called for glx and eglx backends are now shared and moved into
|
|
a clutter_x11 prefix.
|
|
|
|
* Scaling with gravity functionality was replaced by more generic and
|
|
powerful anchor point.
|
|
|
|
* The ClutterLayout interface, the ClutterBox and its implementations have
|
|
been moved outside Clutter core.
|
|
|
|
* The Effects API has been simplified, and it only requires the final value
|
|
of the effect instead of both the start and end value.
|
|
|
|
* The per-axis rotation API has been deprecated in favour of a single
|
|
pair of accessors, clutter_actor_set_rotation() and
|
|
clutter_actor_get_rotation().
|
|
|
|
* Every actor sub-class that is overriding the ClutterActor::request_coords()
|
|
virtual function *must* chain up to the parent's implementation in order
|
|
to store the bounding box inside the ClutterActor private data.
|
|
|
|
* It is now impossible to call clutter_actor_destroy() on the stage. Backends
|
|
will have to unset the CLUTTER_ACTOR_IS_TOPLEVEL private flag to actually
|
|
destroy the stage.
|
|
|
|
* The default value of the ClutterLabel:wrap property has been changed from
|
|
TRUE to FALSE.
|
|
|
|
* All the behaviours properties have been renamed to match the $PROPERTY-start
|
|
and $PROPERTY-end convention.
|
|
|
|
* The clutter_group_add() function has been "undeprecated" and reimplemented
|
|
as a commodity macro; a clutter_stage_add() commodity macro has also been
|
|
added. Both macros just safely wrap clutter_container_add_actor().
|
|
|
|
* The ClutterContainer::find_child_by_id() virtual function has been removed;
|
|
Clutter keeps track of every actor, so there's no need to recurse into
|
|
containers anymore.
|
|
|
|
* The unused ClutterActor::set_depth() and ClutterActor::get_depth() virtual
|
|
functions have been removed.
|
|
|
|
* It is now possible to roundtrip the string created by
|
|
clutter_color_to_string() to clutter_color_parse().
|
|
|
|
* The amount of motion events is now being throttled using the default frame
|
|
rate setting as the base value to compute the default and maximum frequency
|
|
of motion events to be delivered to every actor.
|
|
|
|
* ClutterAngle usage has been removed from the public API: it is an internal
|
|
optimization, which can be used for faster angle computations; users of
|
|
ClutterAngle now take a fixed point number in form of a ClutterFixed.
|
|
|
|
* ClutterGravity usage when scaling has been superceded by the anchor point.
|
|
|
|
* The precision of the clutter_sqrti() algorithm has been improved for small
|
|
values.
|
|
|
|
* ClutterBehaviourScale constructor, scale properties and accessors have
|
|
been changed to accomodate the scaling factors on both the X and Y axis,
|
|
matching the clutter_actor_set_scale() function. This also changed the
|
|
clutter_effect_scale() function, which now accepts the final scale
|
|
factor on both the X and Y axis. The gravity property has also been
|
|
removed, as it behaved incorrectly with regards to the anchor point. When
|
|
scaling an actor using a BehaviourScale, the anchor point should be set
|
|
before applying the behaviour (remember to adjust the positioning as
|
|
well by factoring in the anchor point).
|
|
|
|
* The clutter_do_event() is now public; it can be used to feed an event to
|
|
Clutter and let it generate the capture-bubble signal emissions; it should
|
|
not be used by applications.
|
|
|
|
* In the X11-based backends, the DestroyNotify event is not propagated to
|
|
Clutter core if the stage is using a foreign window.
|
|
|
|
* To avoid method name collisions between ClutterActor and ClutterEntry
|
|
in high-level languages, the clutter_entry_set_position() and
|
|
clutter_entry_get_position() functions have been renamed to
|
|
clutter_entry_set_cursor_position() and clutter_entry_get_cursor_position()
|
|
respectively.
|
|
|
|
Release Notes for Clutter 0.4.0
|
|
-------------------------------
|
|
|
|
* clutter_actor_show_all does not recurse for groups at least (this is to
|
|
match the original group_show_all behaviour). This is like 0.3 but was
|
|
never noted.
|
|
|
|
* ClutterBox API has changed: clutter_box_pack_start() and
|
|
clutter_box_pack_end() have been removed in favour of the clutter_box_pack()
|
|
API.
|
|
|
|
* Both clutter_threads_enter() and clutter_threads_leave() have been
|
|
removed from the API, as they just created confusion and the wrong
|
|
idea that Clutter is either thread-safe or thread-aware. Full
|
|
thread-awareness is arriving in the next revision (see bug #429).
|
|
|
|
* The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been
|
|
overhauled.
|
|
|
|
Release Notes for Clutter 0.3.1
|
|
-------------------------------
|
|
|
|
* clutter_actor_apply_transform_to_point() parameters changed to use
|
|
ClutterVertices.
|
|
|
|
* New 'Native API' backend expects EGL implementation to provide a
|
|
CreateNativeWindow() API call.
|
|
|
|
* Exisiting X11 based egl backend public API calls now prefixed eglx.
|
|
|
|
Release Notes for Clutter 0.3
|
|
-----------------------------
|
|
|
|
* ClutterTexture changes:
|
|
+ clutter_texture_set_pixbuf() now takes a GError paremeter.
|
|
+ clutter_texture_upload_data has been split into two new and
|
|
more functional versions; clutter_texture_set_from_rgb_data(),
|
|
clutter_texture_set_from_yuv_data().
|
|
|
|
* The GLX specific API has been moved to the GLX backend code and
|
|
it's now under the ClutterGlx namespace.
|
|
|
|
* The priority of the various users of the GLib main loop has been
|
|
reviewed and changed were necessary. Every paint is queued with a
|
|
priority of G_PRIORITY_DEFAULT + 10; timelines are allocated with
|
|
a G_PRIORITY_DEFAULT + 30 priority; events are processed with a
|
|
G_PRIORITY_DEFAULT priority. This ensures that events are processed
|
|
before the paints take place.
|
|
|
|
* The ClutterActor::allocate_coords() has been renamed to
|
|
ClutterActor::query_coords(), in order to clarify its usage.
|
|
|
|
* Actors overriding ClutterActor::request_coords() and
|
|
ClutterActor::query_coords() must convert sizes obtained from the
|
|
public API from pixels to ClutterUnits, using the conversion
|
|
macros found in clutter-units.h. The conversion will be necessary
|
|
until the public API will switch over to returning the generic
|
|
units too.
|
|
|
|
* Users of Intel video cards should find that disabling sync-to-vblank
|
|
is no longer necessary. In case Clutter applications take really
|
|
long times for redrawing and appear stuck and unresponsive, the
|
|
sync-to-vblank feature might still be the culprit; in that case, use
|
|
"export CLUTTER_VBLANK=none" to disable it and file a bug reporting the
|
|
video card model, the driver version and the X server version.
|
|
|
|
* ClutterTimeline objects now share the same timeout pool (see the
|
|
ClutterTimeoutPool API). This might cause problems with heavily
|
|
threaded libraries without integration with the GLib main loop.
|
|
If an application experiences bad behaviours during animations
|
|
use "export CLUTTER_TIMELINE=no-pool" to disable the timeout pool.
|
|
|
|
* clutter_color_parse() now handles color definitions with alpha. Alpha
|
|
will default to fully Opaque rather than fully transparent if not specified.
|
|
|
|
* The Clutter examples/ directory has been removed and replaced with a
|
|
tests/ directory.
|
|
|
|
* The ClutterEvent API has been changed, and specific functions have been
|
|
removed in favour of event-agnostic ones.
|
|
|
|
* The ClutterStage::input-event signal has been removed. All the events now
|
|
emit the ClutterStage::event and ClutterStage::event-after signals, for
|
|
generic event handling.
|
|
|
|
* Runtime options now dependant on backend.
|
|
|
|
* ClutterGroup API to add, remove and list children has been deprecated in
|
|
favour of ClutterContainer API. The ClutterGroup::add and
|
|
ClutterGroup::remove signals have been deprecated:
|
|
ClutterContainer::actor-added and ClutterContainer::actor-removed should
|
|
be used instead.
|
|
|
|
$LastChangedDate$
|