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