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