docs: Update the release notes
[profile/ivi/clutter.git] / README.in
1 README for Clutter @CLUTTER_VERSION@
2 ===============================================================================
3
4 Clutter is an open source software library for creating fast, compelling,
5 portable, and dynamic graphical user interfaces.
6
7 REQUIREMENTS
8 -------------------------------------------------------------------------------
9
10 Clutter currently requires:
11
12   • GLib ≥ @GLIB_REQ_VERSION@
13   • Cogl ≥ @COGL_REQ_VERSION@
14   • JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@
15   • Atk ≥ @ATK_REQ_VERSION@
16   • Cairo ≥ @CAIRO_REQ_VERSION@
17   • PangoCairo ≥ @PANGO_REQ_VERSION@
18
19 When building the X11 backend, Clutter depends on the following extensions:
20
21   • XComposite ≥ @XCOMPOSITE_REQ_VERSION@
22   • XDamage
23   • XExt
24   • XFixes ≥ @XFIXES_REQ_VERSION@
25   • XInput (1.x or 2.x)
26   • XKB
27
28 When building the Wayland backend, Clutter also depends on:
29
30   • wayland-client
31   • xkbcommon
32
33 When building the GDK backend, Clutter also depends on:
34
35   • gdk-3.0 > @GDK_REQ_VERSION@
36
37 When building the CEx100 backend, Clutter also depends on:
38
39   • libgdl
40
41 If you are building the API reference you will also need:
42
43   • GTK-Doc ≥ @GTK_DOC_REQ_VERSION@
44
45 If you are building the additional documentation you will also need:
46
47   • xsltproc
48   • jw (optional, for generating PDFs)
49
50 If you are building the Introspection data you will also need:
51
52   • GObject-Introspection ≥ @GI_REQ_VERSION@
53
54 GObject-Introspection is available from:
55
56   git://git.gnome.org/gobject-introspection
57
58 If you want support for profiling Clutter you will also need:
59
60   • UProf ≥ @UPROF_REQ_VERSION@
61
62 UProf is available from:
63
64   git://github.com/rib/UProf.git
65
66 RESOURCES
67 -------------------------------------------------------------------------------
68
69 The official Clutter website is:
70
71    http://www.clutter-project.org/
72
73 The API references for the latest stable release are available at:
74
75    http://docs.clutter-project.org/docs/clutter/stable/
76    http://docs.clutter-project.org/docs/cogl/stable/
77    http://docs.clutter-project.org/docs/cally/stable/
78
79 The Clutter Cookbook is available at:
80
81    http://docs.clutter-project.org/docs/clutter-cookbook/@CLUTTER_API_VERSION@/
82
83 New releases of Clutter are available at:
84
85    http://source.clutter-project.org/sources/clutter/
86    http://download.gnome.org/sources/clutter/
87
88 The Clutter blog is available at:
89
90    http://www.clutter-project.org/blog/
91
92 To subscribe to the Clutter mailing lists and read the archives, use the
93 Mailman web interface available at:
94
95    http://lists.clutter-project.org/
96
97 New bug page on Bugzilla:
98
99    http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
100
101 Clutter is licensed under the terms of the GNU Lesser General Public
102 License, version 2.1 or (at your option) later.
103
104 BUILDING AND INSTALLATION
105 -------------------------------------------------------------------------------
106
107 To build Clutter from a release tarball, the usual autotool triad should
108 be followed:
109
110   $ ./configure
111   $ make
112   # make install
113
114 To build Clutter from a Git clone, run the autogen.sh script instead
115 of the configure one. The autogen.sh script will run the configure script
116 for you, unless the NOCONFIGURE environment variable is set to a non-empty
117 value.
118
119 See also the wiki page:
120
121   http://wiki.clutter-project.org/wiki/BuildingClutter
122
123 Clutter has additional command line options for the configure script:
124
125  --enable-debug=[no/minimum/yes]
126         Controls Clutter debugging level:
127
128         yes:
129                 All GLib asserts, checks and support for runtime Clutter
130                 debugging notes through CLUTTER_DEBUG. This is the default
131                 value for developers snapshots.
132
133         minimum:
134                 Just GType cast checks and support for runtime Clutter
135                 debugging notes through CLUTTER_DEBUG. This is the default
136                 for stable releases.
137
138         no:
139                 No GLib asserts or checks and no support for runtime Clutter
140                 debugging notes. Only use in extreme performance and/or size
141                 optimization cases, though it is strongly discouraged.
142
143  --enable-maintainer-flags=[no/yes/error]
144         Use strict compiler flags. This defaults to 'yes' for building from
145         Git to 'no' for tarball releases. If 'error' is used, then -Werror
146         will be enabled (if available).
147
148  --enable-gtk-doc
149         use gtk-doc to build API documentation (default=no). Requires gtk-doc
150         present on the target system.
151
152  --enable-docs=[no/yes]
153         Build additional documentation. Requires xsltproc for DocBook
154         conversion, and optionally jw for PDF generation.
155
156  --enable-gcov=[no/yes]
157         Build Clutter with coverage report support, provided by gcov. This
158         feature only works with the GNU Compiler Suite and gcov installed.
159
160  --enable-profile=[no/yes]
161         Build Clutter with profiling instrumentation. Requires the GNU
162         C Compiler and the UProf library.
163
164  --enable-conform=[yes/no]
165         Build the Clutter conformance test suite.
166
167  --enable-deprecated=[yes/no]
168         Whether deprecated symbols should be available when compiling Clutter.
169
170  --disable-Bsymbolic
171         Disable linking with -Bsymbolic.
172
173  --enable-x11-backend=[yes/no/check]
174         Enable the X11 backend. (default=check)
175
176  --enable-win32-backend=[yes/no/check]
177         Enable the native Microsoft Windows backend. (default=check)
178
179  --enable-quartz-backend=[yes/no/check]
180         Enable the native Quartz backend. (default=check)
181
182  --enable-gdk-backend=[yes/no/check]
183         Enable the GDK backend. (default=check)
184
185  --enable-wayland-backend=[yes/no]
186         Enable the Wayland client backend. (default=no) [EXPERIMENTAL]
187
188  --enable-cex100-backend=[yes/no]
189         Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL]
190
191  --enable-egl-backend=[yes/no]
192         Enable the EGL framebuffer backend. (default=no)
193
194  --enable-tslib-input=[yes/no]
195         Enable the TSLib input backend. (default=no) [EXPERIMENTAL]
196
197  --enable-evdev-input=[yes/no]
198         Enable the evdev input backend. (default=no) [EXPERIMENTAL]
199
200 See also the INSTALL file generated by autotools for further information.
201
202 VERSIONING
203 -------------------------------------------------------------------------------
204
205 Clutter uses the common "Linux kernel" versioning system, where
206 even-numbered minor versions are stable and odd-numbered minor
207 versions are development snapshots.
208
209 Different major versions break both API and ABI but are parallel
210 installable. The same major version with differing minor version is
211 expected to be ABI compatible with other minor versions; differing
212 micro versions are meant just for bug fixing. On odd minor versions
213 the newly added API might still change.
214
215 The micro version indicates the origin of the release: even micro
216 numbers are only used for released archives; odd micro numbers are
217 only used on the Git repository.
218
219 HACKING
220 -------------------------------------------------------------------------------
221
222 If you want to hack on and improve Clutter check the HACKING file for
223 general implementation guidelines, and the HACKING.backends for
224 backend-specific implementation issues.
225
226 The CODING_STYLE file contains the rules for writing code conformant to the
227 style guidelines used throughout Clutter. Remember: the coding style is
228 mandatory; patches not conforming to it will be rejected by default.
229
230 BUGS
231 -------------------------------------------------------------------------------
232
233 Bugs should be reported to the Clutter Bugzilla at:
234
235   http://bugzilla.gnome.org/enter_bug.cgi?product=clutter
236
237 You will need a Bugzilla account.
238
239 In the report you should include:
240
241   • what system you're running Clutter on;
242   • which version of Clutter you are using;
243   • which version of GLib and OpenGL (or OpenGL ES) you are using;
244   • which video card and which drivers you are using, including output of
245     glxinfo and xdpyinfo (if applicable);
246   • how to reproduce the bug.
247
248 If you cannot reproduce the bug with one of the tests that come with Clutter
249 source code, you should include a small test case displaying the bad
250 behaviour.
251
252 If the bug exposes a crash, the exact text printed out and a stack trace
253 obtained using gdb are greatly appreciated.
254
255 CONTRIBUTING
256 -------------------------------------------------------------------------------
257
258 Patches should be submitted using Bugzilla. Patches fixing a bug should be
259 attached to the bug report; patches for new features or for fixing bugs not
260 yet reported should be attached to a newly opened bug.
261
262 Patches should always be in the unified diff format, using:
263
264   diff -Nuarp clutter.source clutter.patched > clutter-patch.diff
265
266 If diffing against the Git repository, you should use:
267
268   git diff > clutter-patch.diff
269
270 Or, better: commit locally and use `git format-patch` to generate a patch
271 containing authorship details, so that members of the Clutter development
272 team can credit your contribution properly.
273
274 Another useful tool for interacting with Git and Bugzilla is git-bz(1):
275
276   http://git.fishsoup.net/man/git-bz.html
277
278 Which is available here:
279
280   http://git.fishsoup.net/cgit/git-bz/
281
282 RELEASE NOTES
283 -------------------------------------------------------------------------------
284
285 Relevant information for developers with existing Clutter applications
286 wanting to port to newer releases (see NEWS for general information on new
287 features).
288
289 Release Notes for Clutter 1.10
290 -------------------------------------------------------------------------------
291
292 • The long since broken depth cueing support in ClutterStage has been
293   deprecated; the fixed pipeline fog API has been pretty much useless
294   since the switch to colors and textures with premultiplied alpha
295   channels. Setting ClutterStage:use-fog to TRUE has no visible results,
296   and querying the :use-fog and :fog properties will always yield the
297   default values.
298
299 • ClutterDeformEffect switched from using CoglVertexBuffer to using the
300   CoglPrimitive API internally, to improve performance and use non-deprecated
301   Cogl API. CoglPrimitive converts COGL_WRAP_MODE_AUTOMATIC to
302   COGL_WRAP_MODE_CLAMP_TO_EDGE, unlike CoglVertexBuffer which converts it to
303   COGL_WRAP_MODE_REPEAT. This prevents artifacts when sampling texture
304   coordinates outside the [ 0, 1 ] range. This change may cause the back
305   texture to not be painted if its coordinates go outside the allowed range,
306   for instance when using a custom transformation matrix on the back material
307   used by the ClutterDeformEffect.
308
309 • The "default stage" has been deprecated; since the 1.0 release, the default
310   stage creation was deferred to the call to clutter_stage_get_default(), and
311   the preferred way for getting a ClutterStage was calling clutter_stage_new()
312   instead. On platforms that do not support multiple stages, attempting to
313   create more than one stage will lead to an error, and Clutter will abort.
314
315 • Clutter can support multiple backends in the same shared library. Only one
316   windowing or input backend can be used at run time. As a result of this
317   change, the shared library name used by Clutter has changed from:
318
319         libclutter-<flavour>-<API version>.so
320
321   to:
322
323         libclutter-<API version>.so
324
325   The pkg-config file has been updated accordingly. Until the next major API
326   break, Clutter will ship compatibility links for all the previous "flavours"
327   that were available in versions < 1.10; this allows applications dynamically
328   linking against Clutter, or using dlopen(), to keep working. For libraries
329   and applications dynamically linking against Clutter, though, it is still
330   recommended to recompile to make sure that the most recent version is being
331   used. Language bindings using GObject Introspection will automatically use
332   the new shared library without requiring any change.
333
334 • The windowing system backend for the CE3100 and CE4100 platforms using the
335   libgdl library is now implemented as a separate backend instance, instead
336   of being a sub-flavour of the EGL native framebuffer backend. This change
337   introduces a new header file, under $includedir/clutter-1.0/clutter/cex100,
338   which should be included to access the CEx100-specific API. The API and
339   ABI of the platform API has not been changed, though it should still be
340   considered experimental.
341
342 • As of 1.10 it is not necessary any more to call clutter_threads_init() to
343   initialize threading support in Clutter; after the changes in GLib 2.32,
344   threading support in Clutter is always enabled. The rules on how to use
345   Clutter from multiple threads haven't changed.
346
347 • Deprecated API is now marked using the CLUTTER_DEPRECATED and the
348   CLUTTER_DEPRECATED_FOR annotations; these two annotations will result in
349   compiler warnings when attempting to use the deprecated API. It is possible
350   to disable deprecation warnings for Clutter by defining the
351   CLUTTER_DISABLE_DEPRECATION_WARNINGS symbol when compiling. The previous
352   deprecation symbol, CLUTTER_DISABLE_DEPRECATED, is only used for macros.
353
354 • Deprecated functionality has been moved to separate header files, installed
355   under the $includedir/clutter-1.0/clutter/deprecated directory. These files
356   are still included by default by clutter/clutter.h.
357
358 Release Notes for Clutter 1.8
359 -------------------------------------------------------------------------------
360
361 • Cogl has been split out of tree. Clutter depends on Cogl, so users should
362   not notice anything. Developers using pkg-config will gain an extra Cogl
363   dependency.
364
365 • The clutter_actor_get_gid() and clutter_get_actor_by_gid() functions have
366   been deprecated. They should not have been public in the first place.
367
368 • ClutterShader and its relative API have been deprecated. ClutterShaderEffect
369   and the effect API is the proper way to use GLSL shaders with ClutterActors.
370   It is possible to instantiate a ClutterShaderEffect directly.
371
372 • ClutterText's paint volume has been implemented using the ink rectangle of
373   the PangoLayout used to paint, to allow culling to work properly even in
374   the case of glyphs spilling outside the logical rectangle.
375
376 • Non fully opaque children of a non fully opaque actor will be composited
377   in an offscreen framebuffer object to preserve the correct overall opacity.
378   This changes the way non fully opaque actors are drawn, and might cause
379   some code relying on the old, unspecified behaviour to produce different
380   results.
381
382 • ClutterBoxLayout layout algorithm has been changed to map the more mature
383   and more stable GtkBox one.
384
385 • The ClutterText:editable property was incorrectly defined in the GParamSpec
386   as being TRUE by default, but it was initialized to FALSE. To avoid breaking
387   existing code, the default value inside the GParamSpec (and inside the
388   documentation) has been changed to FALSE as well.
389
390 • The preferred way to draw inside a ClutterCairoTexture is connecting to
391   its ::draw signal, and calling the invalidate() method. The old pattern
392   of creating the Cairo context using the create() method is deprecated but
393   still working as intended.
394
395 • ClutterScore has been deprecated; the preferred way to chain up multiple
396   animations is to use the ClutterAnimator or ClutterState classes.
397
398 Release Notes for Clutter 1.6
399 -------------------------------------------------------------------------------
400
401 • The internal copy of JSON-GLib has been removed: Clutter now strictly
402   depends on the installed copy of this library. The --with-json configure
403   switch has been removed.
404
405 • The ClutterBehaviour class and its sub-classes have been deprecated; the
406   Clutter API reference contains a migration guide to port code based on
407   behaviours to the implicit animations framework.
408
409 • The ClutterTimeoutPool and clutter_frame_source_* API have been deprecated;
410   both API are not integrated in the Clutter main loop, and are not used
411   internally any longer, so they are of relative use.
412
413 • It it not necessary any more to provide implementations for the
414   ClutterActor::map() and ClutterActor::unmap() virtual functions, even
415   for composite actors not implementing the ClutterContainer interface.
416
417 • ClutterTimeline now guarantees that the ::new-frame signal will be
418   emitted at the beginning of the timeline, as well as guaranteeing that
419   the ::completed signal will be emitted at the end of the timeline.
420
421 • ClutterActor will check for the enabled property of ClutterActorMeta
422   instances (actions, constraints and effects), and will not invoke
423   ClutterActorMeta functions on disabled instances. This removes the
424   requirement for checking the property inside the ClutterActorMeta
425   sub-classes.
426
427 • ClutterActorBox, ClutterGeometry and ClutterVertex install a progress
428   function for ClutterInterval, allowing the interpolation of properties
429   using them as storage types.
430
431 • ClutterColor's clutter_color_from_string() function accepts CSS3 color
432   specifications.
433
434 • The previously unused "axes" field in the ClutterButtonEvent,
435   ClutterScrollEvent and ClutterMotionEvent structures is now used on
436   the X11-based backends with XInput support.
437
438 • ClutterListModel will honour the filter function when calling
439   clutter_model_get_iter_at_row().
440
441 • ClutterClickAction does not use a pointer grab any longer, and uses
442   a capture on the stage instead.
443
444 • On all platforms which allow it, ClutterStage will ask the windowing
445   system for an explicit key focus when showing the stage window. This
446   can be disabled using clutter_stage_set_accept_focus().
447
448 Release Notes for Cogl 1.6
449 -------------------------------------------------------------------------------
450
451 • Cogl may internally optimise cogl_read_pixels when only a single
452   pixel is drawn and the entire scene is comprised of solid colour
453   rectangles. Instead of actually rendering the rectangles it will
454   compute the single pixel value in software. This effectively means
455   that Clutter can do software picking without any API changes.
456
457 • Internally Cogl now has a GLSL backend as well as the ARBfp and
458   fixed function backends. By default, this backend has the lowest
459   priority but it can be explicitly enabled by setting the
460   COGL_DEBUG environment variable, e.g.:
461
462     export COGL_DEBUG=disable-fixed,disable-arbfp
463
464   for builds of Clutter with debug support enabled.
465
466 • Cogl will internally now cache generated ARBfp programs so that it
467   should be able to reuse a previous program even if it was generated
468   for an unrelated CoglMaterial. This makes using one-shot materials
469   less expensive than before although it is still not recommended.
470
471 Release Notes for Clutter 1.4
472 -------------------------------------------------------------------------------
473
474 • ClutterLayoutManager sub-classes overriding the set_container() virtual
475   function should chain up to the parent class's implementation.
476
477 • The ClutterTexture:filename property is now readable, as well as writable;
478   this allows querying the Texture for the filename storing the image data.
479   The value will be unset when using the set_from_*_data() family of
480   functions.
481
482 • If both the :sync-size and the :keep-aspect-ratio properties of a
483   ClutterTexture are set to TRUE, then the texture actor will update its
484   ClutterActor:request-mode property depending on the orientation of the
485   image data - height-for-width for landscape, and width-for-height for
486   portrait. Square image data will default to height-for-width, like all
487   actors. You can still explicitly override the :request-mode value, or
488   you can unset the :sync-size property to control the size yourself.
489
490 • All the key symbol macros have been renamed from CLUTTER_* to
491   CLUTTER_KEY_*. The old names are still available inside the
492   clutter-keysyms-compat.h header, which is included by clutter-keysyms.h
493   unless CLUTTER_DISABLE_DEPRECATED is defined.
494
495 • The internal copy of json-glib is now deprecated. Building Clutter will
496   default to the system copy and requires an explicit --with-json=internal
497   to override the check.
498
499 Release Notes for Clutter 1.2
500 -------------------------------------------------------------------------------
501
502 * ClutterStageManager is now publicly available and documented API.
503
504 * Clutter now depends on the system copy of JSON-GLib, and will fall
505   back to the internal copy only if JSON-GLib is not installed.
506
507 * ClutterActor:opacity is now defined using GParamSpecUint instead of
508   GParamSpecUchar; the same interval of [ 0, 255 ] applies, and GValue
509   has internal transformation functions for converting between G_TYPE_UINT
510   and G_TYPE_UCHAR, so this change should be fully transparent to the
511   user of the code.
512
513 * On X11 Clutter will emulate XKB's detectable key auto-repeat; this means
514   that when holding down a key, Clutter will emit multiple CLUTTER_KEY_PRESS
515   events and a single CLUTTER_KEY_RELEASE event instead of a list of
516   CLUTTER_KEY_PRESS and CLUTTER_KEY_RELEASE pairs.
517
518 * On X11 and Win32 the default Stage is created when
519   clutter_stage_get_default() is called for the first time, and not as
520   part of the stage initialization.
521
522 Cogl API changes for Clutter 1.2
523 -------------------------------------------------------------------------------
524
525 * cogl_viewport is now deprecated in favour of cogl_set_viewport which
526   accepts a viewport offset.
527
528 * cogl_clip_push() is now deprecated and new code should use
529   cogl_clip_push_rectangle() instead. The old API wasn't consistent with other
530   Cogl APIs that specify model space rectangles using (x0,y0)(x1,y1) pairs.
531
532 * cogl_clip_push_window_rect() is now deprecated and new code should use
533   cogl_clip_push_window_rectangle(). The old API shouldn't have been defined
534   to take floats and the abbreviation wasn't consistent with other Cogl API.
535
536 * cogl_clip_stack_save() and cogl_clip_stack_restore() are deprecated, as
537   the functionality is redundant now that offscreen draw buffers own their
538   clip state and switching to/from offscreen rendering will automatically
539   save and restore the clip state.
540
541 * cogl_material_copy() was added. It is advised that developers use
542   this instead of cogl_material_new() when creating a material that is in some
543   way derived from another. This will allow Cogl to track material
544   ancestries/similarities and reduce the cost of GPU state changes.
545
546 * cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now
547   deprecated and new code should use the cogl_framebuffer_* API instead.
548   Code that previously did:
549     cogl_push_draw_buffer ();
550     cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer);
551     /* draw */
552     cogl_pop_draw_buffer ();
553   can now be re-written as:
554     cogl_push_framebuffer (buffer);
555     /* draw */
556     cogl_pop_framebuffer ();
557
558 * All cogl_<type>_ref() and cogl_<type>_unref() functions have been
559   deprecated, and superceded by cogl_handle_ref() and cogl_handle_unref()
560   respectively.
561
562 * The cogl_check_extension() function has been deprecated. This function
563   was never meant to be public, since it depends on calling glGetString()
564   before its invocation. Users of this function can be replaced by the
565   equivalent code:
566
567     gl_ext = glGetString (GL_EXTENSIONS);
568   - has_ext = cogl_check_extension (ext_name, gl_ext);
569   + has_ext = strstr (gl_ext, ext_name) != NULL ? TRUE : FALSE;
570
571 Release Notes for Clutter 1.0
572 -------------------------------------------------------------------------------
573
574 * The clutter_actor_set_shader_param() function now takes a
575   GValue, which can be set using the clutter_value_set_shader()
576   family of functions. The floating point wrapper has been
577   rename clutter_actor_set_shader_param_float() to match the newly
578   added clutter_actor_set_shader_param_int().
579
580 * The Pango renderer API has been exposed as public API, after
581   a full rename from PangoClutter to CoglPango, to avoid namespace
582   collisions with upstream Pango. The Pango font map, renderer and
583   glyph cache can be used by third party code and depend only on
584   COGL.
585
586 * Both Clutter and COGL only allow including <clutter/clutter.h>
587   and <cogl/cogl.h> directly, respectively. This allows avoiding
588   breaking API every time a type definition is moved across
589   headers, and improves the reliability of third party code against
590   internal refactorings.
591
592 * COGL has an internal Color type, used to store a color definition
593   that can be efficiently used with the least amount of conversions
594   by both the GL and GLES implementations. The COGL API has been
595   changed to drop the usage of ClutterColor in favour of CoglColor.
596
597 * The fixed point API implementation Clutter uses internally has been
598   moved from the Clutter namespace to the COGL one.
599
600 * ClutterLabel and ClutterEntry have been removed from the API, as
601   both have been superceded by the ClutterText actor.
602
603 * ClutterCloneTexture has been removed from the API; in its place,
604   there is a generic ClutterClone actor which allows to "clone"
605   any existing actors -- even composite ones -- without using
606   frame buffer objects (FBOs).
607
608 * The ClutterEffectTemplate and clutter_effect_* functions have been
609   superceded by ClutterAnimation and thus removed from the public API.
610
611 * The ClutterBehaviourBspline has been superceded by the usage of
612   ClutterPath inside ClutterBehaviourPath, and thus removed from the
613   public API.
614
615 * ClutterColor API has received a much needed review to increase its
616   consistency. This has led to the following changes:
617
618     - clutter_color_parse() has been renamed to clutter_color_from_string()
619       and the order of the arguments has been changed
620
621     - the factor argument of clutter_color_shade() has been swapped with
622       the return location for the new color
623
624     - the fixed point entry points have been removed
625
626     - clutter_color_from_hls() and clutter_color_to_hls() do not
627       normalize the values in the [ 0, 255 ] interval but use the
628       correct HLS intervals:
629
630          Hue: [ 0, 360 )
631          Luminance: [ 0, 1 ]
632          Saturation: [ 0, 1 ]
633
634 * The ClutterFixed symbols have been completely removed: fixed-point
635   public entry points now take a CoglFixed.
636
637 * The -x and -u API have been removed. All the pixel-based API now
638   takes a float to allow sub-pixel precision; this is true also for
639   properties. WARNING: functions with variadic arguments (like
640   g_object_set(), g_object_get() and clutter_actor_animate()) do not
641   behave very well when dealing with integers instead of expected
642   floating point values, and vice versa. On 32bit machines it will
643   most likely lead to a crash. So:
644
645     g_object_set (actor, "width", 100, NULL);
646
647   is incorrect, and should be changed in:
648
649     g_object_set (actor, "width", 100.0, NULL);
650
651 * Composite actors that do not implement the Container interface
652   should implement the following virtual functions:
653
654     - void map   (ClutterActor*)
655     - void unmap (ClutterActor*)
656
657   and chain up to the parent's implementation after calling
658   clutter_actor_map() or clutter_actor_unmap() on their children.
659
660 * Actors implementing the Container interface that have private
661   children that are not meant to be added/removed through the
662   Container API should implement the:
663
664     - void foreach_with_internals (ClutterContainer*,
665                                    ClutterCallback,
666                                    gpointer);
667
668   virtual function.
669
670 * Actors that perform direct transformations using the COGL API inside
671   their paint() implementation should override the apply_transform()
672   virtual function instead. Implementations of the apply_transform()
673   vfunc must chain up to the implementation of the parent class.
674
675 * The ClutterUnit type and the CLUTTER_UNITS_* conversion macros have
676   been removed: all Actors are now using sub-pixel precision directly
677   throughout the API. The new ClutterUnits type has been added as a
678   generic opaque storage for logical distance values.
679
680 * Timelines are now fully time-based: all the frame-related properties
681   and methods have been removed. ClutterTimeline::new-frame will provide
682   the elapsed milliseconds since the beginning of the Timeline, instead
683   of the current frame number. The clutter_timeline_new() constructor
684   takes the duration of the timeline in milliseconds, and thus it replaces
685   the clutter_timeline_new_for_duration() variant.
686
687 Cogl API changes for Clutter 1.0
688 -------------------------------------------------------------------------------
689
690 * All drawing functions now use a source material to determine how geometry is
691   filled. The source material is set via cogl_set_source. Or the convenience
692   functions cogl_set_source_color and cogl_set_source_texture.
693
694   "drawing functions" include: cogl_rectangle, cogl_texture_rectangle,
695   cogl_texture_multiple_rectangles, cogl_texture_polygon (though the
696   cogl_texture_* funcs have been renamed; see below for details),
697   cogl_path_fill/stroke and cogl_vertex_buffer_draw*.
698
699   cogl_texture_rectangle, cogl_texture_multiple_rectangles and
700   cogl_texture_polygon no longer take a texture handle; instead the current
701   source material is referenced. The functions have also been renamed to:
702   cogl_rectangle_with_texture_coords, cogl_rectangles_with_texture_coords
703   and cogl_polygon respectively.
704
705   Most code that previously did:
706     cogl_texture_rectangle (tex_handle, x, y,...);
707   needs to be changed to now do:
708     cogl_set_source_texture (tex_handle);
709     cogl_rectangle_with_texture_coords (x, y,....);
710
711   In the less likely case where you were blending your source texture with a
712   color like:
713     cogl_set_source_color4ub (r,g,b,a); /* (where r,g,b,a isn't just white) */
714     cogl_texture_rectangle (tex_handle, x, y,...);
715   you will need your own material to do that:
716     material = cogl_material_new ();
717     cogl_material_set_color4ub (r,g,b,a);
718     cogl_material_set_layer (material, 0, tex_handle));
719     cogl_set_source_material (material);
720
721   Code that uses the texture coordinates, 0, 0, 1, 1 don't need to use
722   cogl_rectangle_with_texture_coords since these are the coordinates that
723   cogl_rectangle will use.
724
725   For cogl_texture_polygon; as well as dropping the texture handle, the
726   n_vertices and vertices arguments were transposed for consistency. So
727   code previously written as:
728     cogl_texture_polygon (tex_handle, 3, verts, TRUE);
729   need to be written as:
730     cogl_set_source_texture (tex_handle);
731     cogl_polygon (verts, 3, TRUE);
732
733 * The arguments to cogl_rectangle, cogl_path_rectangle and
734   cogl_path_round_rectangle have been changed - for consistency - from
735   x, y, width, height, to x1, y1, x2, y2.
736
737 * A CoglMatrix type and utility API has been added; this is currently used to
738   support describing texture matrices.
739
740 * cogl_alpha_func has been removed, since this is now controlled using the
741   material API via cogl_material_set_alpha_test_function ()
742
743 * A Cogl Vertex Buffer API has been added that allows you to efficiently
744   manage arrays of vertex attributes in buffers that may be stored on
745   the GPU. These allow you to avoid the costs of repeatedy validating
746   vertex data and mapping it into the GPU.
747
748 * cogl_scale now supports scaling on the z axis
749
750 * cogl_clip_set* and cogl_clip_unset have been renamed to cogl_clip_push and
751   cogl_clip_pop respectively so they self document their stacking semantics.
752
753 * cogl_paint_init was renamed to cogl_clear and no longer disables lighting and
754   fogging. cogl_clear also now takes a mask of the auxiliary buffers you want
755   to clear so you can avoid redundant clears of buffers you aren't using.
756
757 * cogl_fog_set was renamed to cogl_set_fog and it now takes a mode argument
758   giving control over the fogging blend factor equation, so that the
759   density argument isn't just ignored. A cogl_disable_fog function was
760   also added.
761
762 * cogl_get_*_matrix were changed to use the CoglMatrix type instead of
763   GLfloat m[16] arrays.
764
765 * cogl_offscreen_blit_region, cogl_offscreen_blit were removed since they were
766   only implemnted for GL, not GLES, and it was assumed no one was using them.
767
768 * cogl_offscreen_new_multisample was removed since it only ever returned
769   COGL_INVALID_HANDLE so it wasn't usefull.
770
771 * The COGL_MASK_BUFFER type was removed, since there should be nicer ways of
772   exposing color mask if anyone wants it later. It was assumed that no one was
773   using this currently.
774
775 * COGLenum, COGLint and COGLuint which were simply typedefs for
776   GL{enum,int,uint} have been removed from the API and replaced with
777   specialised enum typedefs, int and unsigned int. These were causing
778   problems for generating bindings and also considered poor style.
779
780 * The cogl texture filter defines CGL_NEAREST and CGL_LINEAR etc are now
781   replaced by a namespaced typedef 'CoglTextureFilter' so they should be
782   replaced with COGL_TEXTURE_FILTER_NEAREST and COGL_TEXTURE_FILTER_LINEAR etc.
783
784 * The shader type defines CGL_VERTEX_SHADER and CGL_FRAGMENT_SHADER are handled
785   by a CoglShaderType typedef and should be replaced with
786   COGL_SHADER_TYPE_VERTEX and COGL_SHADER_TYPE_FRAGMENT.
787
788 * cogl_shader_get_parameteriv has been replaced by cogl_shader_get_type and
789   cogl_shader_is_compiled. More getters can be added later if desired.
790
791 * cogl_enable_depth_test has been renamed to cogl_set_depth_test_enabled and
792   a corresponding cogl_get_depth_test_enabled function has been added.
793
794 Release Notes for Clutter 0.8
795 -------------------------------------------------------------------------------
796
797 * The COGL GL wrapper API has been completely overhauled and now
798   contains many new features including new greatly improved texture
799   abstractions (slicing, mipmapping, deformations etc, greatly
800   simplifying ClutterTexture), image loading and abstraction, path
801   based primitive drawing, clipping, and improved FBO and shader
802   support. It is now also fully documented.
803
804 * GL Texture Rectangle ext is no longer used, the regular 2D NPOTS
805   extension is preffered instead but not required.
806
807 * Clutter now has basic suppport for multiple input devices assuming
808   the backend supports it (currently X11 based via XInput and Fruity
809   backends). New API supporting this includes
810   clutter_event_get_device_id, clutter_get_input_device_for_id,
811   clutter_grab_pointer_for_device & clutter_ungrab_pointer_for_device.
812
813   XInput support needs to be explicitly enabled at runtime by calling
814   clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput ()
815   can then be called after to check if XInput extension present and use-able.
816
817 * The functions that return the transformed position of an actor have
818   been renamed to be more explicit about it:
819
820     clutter_actor_get_abs_position - clutter_actor_get_transformed_position
821     clutter_actor_get_abs_size     - clutter_actor_get_transformed_size
822
823   Their behaviour has not been changed.
824
825 * To increase portability, Clutter does not strictly depend on
826   GdkPixbuf anymore; this means that you will have to include
827   <gdk-pixbuf/gdk-pixbuf.h> yourself if you are operating with
828   GdkPixbuf objects and not including that header. The GdkPixbuf-based
829   API has been removed from Clutter core:
830
831     clutter_texture_new_from_pixbuf
832     clutter_texture_set_pixbuf
833     clutter_texture_get_pixbuf
834
835   are all deprecated functions. It is still possible to load a GdkPixbuf
836   into a ClutterTexture with this sample code:
837
838     clutter_texture_set_from_rgb_data (texture,
839                                        gdk_pixbuf_get_pixels (pixbuf),
840                                        gdk_pixbuf_get_has_alpha (pixbuf),
841                                        gdk_pixbuf_get_width (pixbuf),
842                                        gdk_pixbuf_get_height (pixbuf),
843                                        gdk_pixbuf_get_rowstride (pixbuf),
844                                        gdk_pixbuf_get_has_alpha (pixbuf) ? 4
845                                                                          : 3,
846                                        0,
847                                        &error);
848
849   ClutterTexture also now has a new filename property and
850   clutter_texture_new_from_file which is intended as an alternate to
851   common previous GdkPixbuf primary usage (i.e loading images from
852   disk).
853
854   To read texture data back into a pixbuf or system memory use a combination
855   of clutter_texture_get_cogl_texture & cogl_texture_get_data.
856
857   The clutter-gtk integration library has API for using GdkPixbuf with
858   ClutterTextures (among others).
859
860   ClutterTexture now supports a keep-aspect property which is set to FALSE
861   by default.
862
863 * clutter_texture_from_actor will now reparent source actors if they
864   are not parented. This behaviour may change in future releases.
865   There are known not yet fixed issues with source actors that set
866   depth or use clipping.
867
868 * The size negotiation API has been completely changed in order to allow
869   the creation of non-fixed layout managers. These functions have been
870   removed:
871
872     clutter_actor_request_coords()
873     clutter_actor_query_coords()
874
875   from the ClutterActor API, as well as their virtual functions inside
876   the ClutterActorClass. The size of an actor is now split into two
877   different concepts: the preferred size (width and height
878   separatedly) and the size that has been allocated by the container
879   to which that actor belongs. Clutter still defaults to the fixed
880   layout management (i.e ClutterGroup) of the actors, but supports
881   fluid layout managers written using the new API.
882
883   Composite actors (actors with 'private' children not implementing the
884   container interface) now need to implement an allocate method here pass
885   an allocation to any composite children.
886
887 * Clutter now depends on PangoCairo for the font rendering. The PangoClutter
888   API is still considered semi-private and no guarantees are made on its
889   stability.
890
891 * ClutterShader API has been slightly changed: the ClutterStage:bound
892   property, clutter_shader_bind() and clutter_shader_is_bound() have
893   been renamed to :compiled, clutter_shader_compile() and
894   clutter_shader_is_compiled(), respectively. The previously semi-private
895   clutter_shader_release_all() function is now not exported anymore.
896
897 * ClutterStage is not an abstract type anymore: it can be instantiated
898   using clutter_stage_new() and it can be properly subclassed. If the
899   backend supports multiple stages, every stage will be a new window,
900   whose lifetime will have to be managed by the developer. Clutter will
901   still create the default stage, and guarantees that every call to
902   clutter_stage_get_default() will return exactly the same pointer.
903
904 * Actors now have a new 'show-on-set-parent' property set to TRUE by
905   default. With this property set to TRUE, actors will automatically
906   have clutter_actor_show() called on them when a parent is set (i.e
907   added to a container).
908
909 * Clutter now features support for multiple stages assuming supported
910   by the backend. See test-multistage.c for example of usage. This
911   does not change the automatic creation of the default stage.
912   A single GL context is used across all stages meaning GL resources
913   are shared.
914
915 * There is now an experimental native iPod Touch/iPhone UIKit backend
916   named 'fruity'.
917
918 * There is now an experimental native Win32 WGL backend.
919
920 * COGL (and therefor Clutter) now optionally features initial support for
921   OpenGL ES 2.0. It features support for shaders.
922
923 * Some more focused timeline unit tests have been added and some tweaks to
924   timeline semantics were made; E.g. For a 10 frame timeline here are some
925   points about the semantics:
926   - When you create a timeline it starts with current_frame_num == 0
927   - After starting a timeline, the first timeout is for current_frame_num == 1
928     (Notably it isn't 0 since there is a delay before the first timeout signals
929     so re-asserting the starting frame (0) wouldn't make sense.)
930   - For a non looping timeline the last timeout would be for
931     current_frame_num == 10
932   - For a looping timeline the timeout for current_frame_num == 10 would be
933     followed by a timeout for current_frame_num == 1 and frame 0 is considered
934     == frame 10.
935   - Asking for a timeline of N frames might better be described as asking for
936     a timeline of _length_ N.
937
938 * The behaviour of clutter_actor_get_opacity() has been slightly changed;
939   instead of returning the composited opacity of the entire parents chain
940   of an actor, clutter_actor_get_opacity() does what you mean, and returns
941   the opacity set with clutter_actor_set_opacity(). The composited
942   opacity value is now returned by clutter_actor_get_paint_opacity().
943
944 * Until 0.6, clutter_label_get_color() would have returned a ClutterColor
945   with the alpha component equal to the composited opacity of the label.
946   Now, clutter_label_get_color() returns a copy of the exact color set
947   with clutter_label_set_color().
948
949 * The ClutterEntry actor will automatically handle key events inside
950   a key-press-event handler. This deprecates the usage of
951   clutter_entry_handle_key_event() to update the contents of the
952   entry using the ClutterKeyEvent.
953
954 * The Clutter X11 and GLX backends feature support for wrapping external
955   X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX
956   extension if available and fallback to slower XGetImage copies if not.
957
958 * ClutterContainer can have per child custom properties via ClutterChildMeta.
959
960 Release Notes for Clutter 0.6
961 -------------------------------------------------------------------------------
962
963 * Now that every actor has events, the class signal handlers have been
964   removed from ClutterStageClass and moved into ClutterActorClass.
965
966 * The CLUTTER_2BUTTON_PRESS and CLUTTER_3BUTTON_PRESS event types have been
967   removed in favour of the ClutterButtonEvent:click_count counter
968
969 * X11 related called for glx and eglx backends are now shared and moved into
970   a clutter_x11 prefix.
971
972 * Scaling with gravity functionality was replaced by more generic and
973   powerful anchor point.
974
975 * The ClutterLayout interface, the ClutterBox and its implementations have
976   been moved outside Clutter core.
977
978 * The Effects API has been simplified, and it only requires the final value
979   of the effect instead of both the start and end value.
980
981 * The per-axis rotation API has been deprecated in favour of a single
982   pair of accessors, clutter_actor_set_rotation() and
983   clutter_actor_get_rotation().
984
985 * Every actor sub-class that is overriding the ClutterActor::request_coords()
986   virtual function *must* chain up to the parent's implementation in order
987   to store the bounding box inside the ClutterActor private data.
988
989 * It is now impossible to call clutter_actor_destroy() on the stage. Backends
990   will have to unset the CLUTTER_ACTOR_IS_TOPLEVEL private flag to actually
991   destroy the stage.
992
993 * The default value of the ClutterLabel:wrap property has been changed from
994   TRUE to FALSE.
995
996 * All the behaviours properties have been renamed to match the $PROPERTY-start
997   and $PROPERTY-end convention.
998
999 * The clutter_group_add() function has been "undeprecated" and reimplemented
1000   as a commodity macro; a clutter_stage_add() commodity macro has also been
1001   added. Both macros just safely wrap clutter_container_add_actor().
1002
1003 * The ClutterContainer::find_child_by_id() virtual function has been removed;
1004   Clutter keeps track of every actor, so there's no need to recurse into
1005   containers anymore.
1006
1007 * The unused ClutterActor::set_depth() and ClutterActor::get_depth() virtual
1008   functions have been removed.
1009
1010 * It is now possible to roundtrip the string created by
1011   clutter_color_to_string() to clutter_color_parse().
1012
1013 * The amount of motion events is now being throttled using the default frame
1014   rate setting as the base value to compute the default and maximum frequency
1015   of motion events to be delivered to every actor.
1016
1017 * ClutterAngle usage has been removed from the public API: it is an internal
1018   optimization, which can be used for faster angle computations; users of
1019   ClutterAngle now take a fixed point number in form of a ClutterFixed.
1020
1021 * ClutterGravity usage when scaling has been superceded by the anchor point.
1022
1023 * The precision of the clutter_sqrti() algorithm has been improved for small
1024   values.
1025
1026 * ClutterBehaviourScale constructor, scale properties and accessors have
1027   been changed to accomodate the scaling factors on both the X and Y axis,
1028   matching the clutter_actor_set_scale() function. This also changed the
1029   clutter_effect_scale() function, which now accepts the final scale
1030   factor on both the X and Y axis. The gravity property has also been
1031   removed, as it behaved incorrectly with regards to the anchor point. When
1032   scaling an actor using a BehaviourScale, the anchor point should be set
1033   before applying the behaviour (remember to adjust the positioning as
1034   well by factoring in the anchor point).
1035
1036 * The clutter_do_event() is now public; it can be used to feed an event to
1037   Clutter and let it generate the capture-bubble signal emissions; it should
1038   not be used by applications.
1039
1040 * In the X11-based backends, the DestroyNotify event is not propagated to
1041   Clutter core if the stage is using a foreign window.
1042
1043 * To avoid method name collisions between ClutterActor and ClutterEntry
1044   in high-level languages, the clutter_entry_set_position() and
1045   clutter_entry_get_position() functions have been renamed to
1046   clutter_entry_set_cursor_position() and clutter_entry_get_cursor_position()
1047   respectively.
1048
1049 Release Notes for Clutter 0.4.0
1050 -------------------------------------------------------------------------------
1051
1052 * clutter_actor_show_all does not recurse for groups at least (this is to
1053   match the original group_show_all behaviour). This is like 0.3 but was
1054   never noted.
1055
1056 * ClutterBox API has changed: clutter_box_pack_start() and
1057   clutter_box_pack_end() have been removed in favour of the clutter_box_pack()
1058   API.
1059
1060 * Both clutter_threads_enter() and clutter_threads_leave() have been
1061   removed from the API, as they just created confusion and the wrong
1062   idea that Clutter is either thread-safe or thread-aware. Full
1063   thread-awareness is arriving in the next revision (see bug #429).
1064
1065 * The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been
1066   overhauled.
1067
1068 Release Notes for Clutter 0.3.1
1069 -------------------------------------------------------------------------------
1070
1071 * clutter_actor_apply_transform_to_point() parameters changed to use
1072   ClutterVertices.
1073
1074 * New 'Native API' backend expects EGL implementation to provide a
1075   CreateNativeWindow() API call.
1076
1077 * Exisiting X11 based egl backend public API calls now prefixed eglx.
1078
1079 Release Notes for Clutter 0.3
1080 -------------------------------------------------------------------------------
1081
1082 * ClutterTexture changes:
1083   + clutter_texture_set_pixbuf() now takes a GError paremeter.
1084   + clutter_texture_upload_data has been split into two new and
1085     more functional versions; clutter_texture_set_from_rgb_data(),
1086     clutter_texture_set_from_yuv_data().
1087
1088 * The GLX specific API has been moved to the GLX backend code and
1089   it's now under the ClutterGlx namespace.
1090
1091 * The priority of the various users of the GLib main loop has been
1092   reviewed and changed were necessary. Every paint is queued with a
1093   priority of G_PRIORITY_DEFAULT + 10; timelines are allocated with
1094   a G_PRIORITY_DEFAULT + 30 priority; events are processed with a
1095   G_PRIORITY_DEFAULT priority. This ensures that events are processed
1096   before the paints take place.
1097
1098 * The ClutterActor::allocate_coords() has been renamed to
1099   ClutterActor::query_coords(), in order to clarify its usage.
1100
1101 * Actors overriding ClutterActor::request_coords() and
1102   ClutterActor::query_coords() must convert sizes obtained from the
1103   public API from pixels to ClutterUnits, using the conversion
1104   macros found in clutter-units.h. The conversion will be necessary
1105   until the public API will switch over to returning the generic
1106   units too.
1107
1108 * Users of Intel video cards should find that disabling sync-to-vblank
1109   is no longer necessary. In case Clutter applications take really
1110   long times for redrawing and appear stuck and unresponsive, the
1111   sync-to-vblank feature might still be the culprit; in that case, use
1112   "export CLUTTER_VBLANK=none" to disable it and file a bug reporting the
1113   video card model, the driver version and the X server version.
1114
1115 * ClutterTimeline objects now share the same timeout pool (see the
1116   ClutterTimeoutPool API). This might cause problems with heavily
1117   threaded libraries without integration with the GLib main loop.
1118   If an application experiences bad behaviours during animations
1119   use "export CLUTTER_TIMELINE=no-pool" to disable the timeout pool.
1120
1121 * clutter_color_parse() now handles color definitions with alpha. Alpha
1122   will default to fully Opaque rather than fully transparent if not specified.
1123
1124 * The Clutter examples/ directory has been removed and replaced with a
1125   tests/ directory.
1126
1127 * The ClutterEvent API has been changed, and specific functions have been
1128   removed in favour of event-agnostic ones.
1129
1130 * The ClutterStage::input-event signal has been removed. All the events now
1131   emit the ClutterStage::event and ClutterStage::event-after signals, for
1132   generic event handling.
1133
1134 * Runtime options now dependant on backend.
1135
1136 * ClutterGroup API to add, remove and list children has been deprecated in
1137   favour of ClutterContainer API. The ClutterGroup::add and
1138   ClutterGroup::remove signals have been deprecated:
1139   ClutterContainer::actor-added and ClutterContainer::actor-removed should
1140   be used instead.