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