mutter/README
Emmanuele Bassi 8c451b8a67 2008-02-20 Emmanuele Bassi <ebassi@openedhand.com>
* clutter/clutter-actor.h:
	* clutter/clutter-actor.c:
	(clutter_actor_get_abs_opacity): Add function that does what
	get_opacity() does now...

	(clutter_actor_get_opacity): ... and make get_opacity() do what
	it's supposed to be doing. The original get_opacity() returned
	a composited value, and there's no way to actually extract the
	real opacity value set with set_opacity().

	* clutter/clutter-clone-texture.c:
	* clutter/clutter-rectangle.c:
	* clutter/clutter-texture.c: Update to use get_abs_opacity().

	* clutter/clutter-entry.c:
	* clutter/clutter-label.c: Ditto. Also, never change the stored
	alpha value. (#804)

	* tests/Makefile.am:
	* tests/test-opacity.c: Test suite for the get_opacity() and
	get_abs_opacity() API, and correct opacity handling.

	* README: Add note about the change in get_opacity().
2008-02-20 10:59:47 +00:00

337 lines
13 KiB
Plaintext

Clutter 0.7 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
* GdkPixbuf
* Pango >= 1.18
* OpenGL >= 1.2 or OpenGL ES 1.1
* GLX, SDL or an EGL Implementation
The official website is:
http://www.clutter-project.org
The Clutter blog is at
http://www.clutter-project.org/blog
To subscribe to the Clutter mailing list, send mail to:
clutter+subscribe@o-hand.com
The official mailing list archive is:
http://lists.o-hand.com/clutter/
New bug page on Bugzilla:
http://bugzilla.o-hand.com/enter_bug.cgi?product=Clutter
Clutter is LGPL licensed.
INSTALLATION
====
See the INSTALL file. 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]
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 EGL implementation to provide a
createNativeWindow () call. Also optionally supports
tslib for touchscreen events.
sdl: Basic SDL backend, using Open GL. Should provide portability
to Windows and possibly other OS's. (experimental)
osx: OS X backend. (experimental)
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, GdkPixbuf and OpenGL you are using;
* which video card and which drivers you are using, including output of
glxinfo and xdpyinfo;
* how to reproduce the bug.
If you cannot reproduce the bug with one of the tests that come with Clutter
source code, you should include a small test case displaying the bad
behaviour.
If the bug exposes a crash, the exact text printed out and a stack trace
obtained using gdb are greatly appreciated.
PATCHES
====
Patches should be submitted using Bugzilla. Patches fixing a bug should be
attached to the bug report; patches for new features or for fixing bugs not
yet reported should be attached to a newly opened bug. Patches should always
be in the unified diff format, 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.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.
* 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_abs_opacity().
* Until 0.6.0, 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().
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$