README for Clutter @CLUTTER_VERSION@ =============================================================================== Clutter is an open source software library for creating fast, compelling, portable, and dynamic graphical user interfaces. REQUIREMENTS ------------------------------------------------------------------------------- Clutter currently requires: • GLib ≥ @GLIB_REQ_VERSION@ • Cogl ≥ @COGL_REQ_VERSION@ • JSON-GLib ≥ @JSON_GLIB_REQ_VERSION@ • Atk ≥ @ATK_REQ_VERSION@ • Cairo ≥ @CAIRO_REQ_VERSION@ • PangoCairo ≥ @PANGO_REQ_VERSION@ When building the X11 backend, Clutter depends on the following extensions: • XComposite ≥ @XCOMPOSITE_REQ_VERSION@ • XDamage • XExt • XInput (1.x or 2.x) • XKB When building the Wayland backend, Clutter also depends on: • wayland-client • xkbcommon When building the GDK backend, Clutter also depends on: • gdk-3.0 > @GDK_REQ_VERSION@ When building the CEx100 backend, Clutter also depends on: • libgdl When building the evdev input backend, Clutter also depends on: • xkbcommon • libudev ≥ @LIBUDEV_REQ_VERSION@ • libinput ≥ @LIBINPUT_REQ_VERSION@ If you are building the API reference you will also need: • GTK-Doc ≥ @GTK_DOC_REQ_VERSION@ If you are building the additional documentation you will also need: • xsltproc • jw (optional, for generating PDFs) If you are building the Introspection data you will also need: • GObject-Introspection ≥ @GI_REQ_VERSION@ GObject-Introspection is available from: git://git.gnome.org/gobject-introspection RESOURCES ------------------------------------------------------------------------------- The official Clutter website is: http://www.clutter-project.org/ The API references for the latest stable release are available at: https://developer.gnome.org/clutter/stable/ https://developer.gnome.org/cogl/stable/ The Clutter Cookbook is available at: https://developer.gnome.org/clutter-cookbook/ New releases of Clutter are available at: https://download.gnome.org/sources/clutter/ The Clutter blog is available at: http://www.clutter-project.org/ To subscribe to the Clutter mailing list and read the archives, use the Mailman web interface available at: https://mail.gnome.org/mailman/listinfo/clutter-list New bug page on Bugzilla: https://bugzilla.gnome.org/enter_bug.cgi?product=clutter Clutter is licensed under the terms of the GNU Lesser General Public License, version 2.1 or (at your option) later. BUILDING AND INSTALLATION ------------------------------------------------------------------------------- To build Clutter from a release tarball, the usual autotool triad should be followed: $ ./configure $ make # make install To build Clutter from a Git clone, run the autogen.sh script instead of the configure one. The autogen.sh script will run the configure script for you, unless the NOCONFIGURE environment variable is set to a non-empty value. See also the wiki page: https://wiki.gnome.org/Projects/Clutter Clutter has additional command line options for the configure script: --enable-debug=[no/minimum/yes] Controls Clutter debugging level: yes: All GLib asserts, checks and support for runtime Clutter debugging notes through CLUTTER_DEBUG. This is the default value for developers snapshots. minimum: Just GType cast checks and support for runtime Clutter debugging notes through CLUTTER_DEBUG. This is the default for stable releases. no: No GLib asserts or checks and no support for runtime Clutter debugging notes. Only use in extreme performance and/or size optimization cases, though it is strongly discouraged. --enable-maintainer-flags=[no/yes/error] Use strict compiler flags. This defaults to 'yes' for building from Git to 'no' for tarball releases. If 'error' is used, then -Werror will be enabled (if available). --enable-gtk-doc use gtk-doc to build API documentation (default=no). Requires gtk-doc present on the target system. --enable-docs=[no/yes] Build additional documentation. Requires xsltproc for DocBook conversion, and optionally jw for PDF generation. --enable-gcov=[no/yes] Build Clutter with coverage report support, provided by gcov. This feature only works with the GNU Compiler Suite and gcov installed. --disable-tests Disable building the Clutter tests suite. --disable-examples Disable building the Clutter API reference examples. --enable-deprecated=[yes/no] Whether deprecated symbols should be available when compiling Clutter. --disable-Bsymbolic Disable linking with -Bsymbolic. --enable-x11-backend=[yes/no/check] Enable the X11 backend. (default=check) --enable-win32-backend=[yes/no/check] Enable the native Microsoft Windows backend. (default=check) --enable-quartz-backend=[yes/no/check] Enable the native Quartz backend. (default=check) --enable-gdk-backend=[yes/no/check] Enable the GDK backend. (default=check) --enable-wayland-backend=[yes/no] Enable the Wayland client backend. (default=no) [EXPERIMENTAL] --enable-cex100-backend=[yes/no] Enable the CEx100 platform backend. (default=no) [EXPERIMENTAL] --enable-egl-backend=[yes/no] Enable the EGL framebuffer backend. (default=no) --enable-tslib-input=[yes/no] Enable the TSLib input backend. (default=no) [EXPERIMENTAL] --enable-evdev-input=[yes/no] Enable the evdev input backend. (default=no) [EXPERIMENTAL] See also the INSTALL file generated by autotools for further information. VERSIONING ------------------------------------------------------------------------------- Clutter uses the common "Linux kernel" versioning system, where even-numbered minor versions are stable and odd-numbered minor versions are development snapshots. Different major versions break both API and ABI but are parallel installable. The same major version with differing minor version is expected to be ABI compatible with other minor versions; differing micro versions are meant just for bug fixing. On odd minor versions the newly added API might still change. The micro version indicates the origin of the release: even micro numbers are only used for released archives; odd micro numbers are only used on the Git repository. HACKING ------------------------------------------------------------------------------- If you want to hack on and improve Clutter check the HACKING file for general implementation guidelines, and the HACKING.backends for backend-specific implementation issues. The CODING_STYLE file contains the rules for writing code conformant to the style guidelines used throughout Clutter. Remember: the coding style is mandatory; patches not conforming to it will be rejected by default. BUGS ------------------------------------------------------------------------------- Bugs should be reported to the Clutter Bugzilla at: http://bugzilla.gnome.org/enter_bug.cgi?product=clutter You will need a Bugzilla account. In the report you should include: • what system you're running Clutter on; • which version of Clutter you are using; • which version of GLib, Cogl, and OpenGL (or OpenGL ES) you are using; • which video card and which drivers you are using, including output of glxinfo and xdpyinfo (if applicable); • how to reproduce the bug. If you cannot reproduce the bug with one of the tests that come with Clutter source code, you should include a small test case displaying the bad behaviour. If the bug exposes a crash, the exact text printed out and a stack trace obtained using gdb are greatly appreciated. CONTRIBUTING ------------------------------------------------------------------------------- Patches should be submitted using Bugzilla. Patches fixing a bug should be attached to the bug report; patches for new features or for fixing bugs not yet reported should be attached to a newly opened bug. Patches should always be in the unified diff format, using: diff -Nuarp clutter.source clutter.patched > clutter-patch.diff If diffing against the Git repository, you should use: git diff > clutter-patch.diff Or, better: commit locally and use `git format-patch` to generate a patch containing authorship details, so that members of the Clutter development team can credit your contribution properly. Another useful tool for interacting with Git and Bugzilla is git-bz(1): http://git.fishsoup.net/man/git-bz.html Which is available here: http://git.fishsoup.net/cgit/git-bz/ Patches submitted against Clutter have to pass the conformance test suite, or, if possible, add new unit tests for the conformance test suite in case of new features. Ensure you run the conformance test suite every for every patch you wish to submit, by using: make -C tests/conform check and verifying that the whole test suite passes. RELEASE NOTES ------------------------------------------------------------------------------- Relevant information for developers with existing Clutter applications wanting to port to newer releases (see NEWS for general information on new features). Release Notes for Clutter 1.26 ------------------------------------------------------------------------------- • The evdev backend specific ClutterPointerConstrainCallback type was changed to include not only the target position but also the previous position. This is an API change, and will require a version check in any caller code. Release Notes for Clutter 1.24 ------------------------------------------------------------------------------- • ClutterModel, ClutterModelIter, and ClutterListStore have been deprecated. You're strongly encouraged to use the GListModel interface, and the GListStore class, as a replacement. • The macros used to access the state flags in ClutterActor have been deprecated, and replaced by equivalent functions. • Clutter types now can be used with the `g_autoptr()` and `g_auto()` macros provided by GLib and supported by GCC and Clang. • The old, non-namespaced CLUTTER_* key symbols now have an associated deprecation warning. • The private, unused ClutterX11XInputEventTypes enumeration, which was erroneously placed in the clutter-x11.h public header, has been removed. • The Wayland client backend is now autodetected depending on whether the required dependencies are available. Release Notes for Clutter 1.22 ------------------------------------------------------------------------------- • The default backend for Clutter starting from this release is the GDK backend, if Clutter was compiled with it. This allows better integration with the underlying windowing system platform on X11 and Wayland. On Windows and MacOS the native backends are still the preferred ones. If you require a specific backend you should use clutter_set_windowing_backend() with the CLUTTER_WINDOWING_* backend you require, prior to call clutter_init(). • The ClutterRequestMode enumeration has a new value. Code checking for the values of ClutterRequestMode should already be resilient to changes to this enumerations, like for all enumerations in Clutter. Release Notes for Clutter 1.20 ------------------------------------------------------------------------------- • The clutter_stage_set_paint_callback() experimental function has been removed from the Clutter ABI; it has been replaced by the ::after-paint signal on the ClutterStage class. The set_paint_callback() method was marked as "experimental", required a special definition to be usable, and no guarantees were made on its continued existence. Release Notes for Clutter 1.18 ------------------------------------------------------------------------------- • Until 1.18, ClutterStage removed its children during its dispose() implementation, before the default ClutterActor::destroy() implementation would run. ClutterStage will now destroy the children when it is destroyed to ensure that the children are destroyed, and that custom code can remove references through the ClutterActor::destroy signal. • Clutter does not depend on the XFIXES extension API on X11 any more. Before 1.18 Clutter used the XFIXES API to hide the cursor; the API is less than useful for toolkits and applications, so Clutter unconditionally uses the fall back code that was in place in case XFIXES was not available. • ClutterText emits the ::insert-text and ::delete-text signals before the contents of the ClutterTextBuffer are changed, as documented. The signal emission cannot be guaranteed if the ClutterTextBuffer API is used instead of the ClutterText API. • Starting from 1.18, the Clutter evdev input device backend no longer uses libevdev and libgudev directly, but relies on libinput for discovering, reading and processing input devices. • The Clutter evdev input device backend was already considered experimental and not subject to Clutter's API and ABI stabitility guarantees. Starting from 1.18, users have to explicitly acknowldge this by having to #define CLUTTER_ENABLE_COMPOSITOR_API to use its public API. Release Notes for Clutter 1.16 ------------------------------------------------------------------------------- • Implicit transitions will not be created on actors that are not mapped, unless they are in a cloned branch of the scene graph. This was never an approved case, as ClutterActor would implicitly skip layout and paint on unmapped actors, but now it's being enforced through the animation machinery as well. Using explicit transitions still works, as explicit transitions completely place the developer in charge. Release Notes for Clutter 1.14 ------------------------------------------------------------------------------- • The X11 backend (both core X events and XInput 2 backends) now mask out scroll lock and num lock modifiers from the event state. Release Notes for Clutter 1.12 ------------------------------------------------------------------------------- • ClutterBinLayout no longer requests or allocates size for children that are not visible, which is how the other layout managers work. • The expansion and alignment layout properties in all the layout managers that provide them have been deprecated in favour of the equivalent ones on ClutterActor; the ClutterLayoutManager implementations provided by Clutter have been updated to honour the ClutterActor:x-expand, ClutterActor:y-expand, ClutterActor:x-align, and ClutterActor:y-align properties, if set. • Setting the ClutterActor:fixed-position-set to FALSE will reset any currently set fixed position to (0, 0). • ClutterActor's margin properties are now animatable. • ClutterBindingActionFunc typedef now has a user_data parameter; the user data was passed by every caller, and ClutterBindingActionFunc was not used anywhere in the API except for documentation purposes. • The clutter_threads_enter() and clutter_threads_leave() functions have been deprecated; the lead to non portable code, and encourage broken behaviour with regards to threaded applications. The only supported, portable way of writing Clutter application employing threads is to defer long running operations to a worker thread, and schedule UI updates to the main loop at well defined synchronization points. Release Notes for Clutter 1.10 ------------------------------------------------------------------------------- • The ClutterActor::paint, ClutterActor::queue-redraw, and ClutterActor::queue-relayout signals are now annotated as not allowing signal emission hooks; this enables some optimization inside GLib, and given the amount of emissions these three signals have, we want to get through all the fast paths we can. • The ClutterActorBox parameter of the ClutterActor::allocation-changed signal is now marked as G_SIGNAL_TYPE_STATIC_SCOPE. • The clutter-stage-window.h header is not installed any more; this header was never meant to be public in the first place, and nothing could have been implementing the ClutterStageWindow interface and use it with Clutter. • ClutterActor will call its unmap() implementation when it is removed from its parent. This may happen after the ClutterActor::destroy signal has been emitted, i.e. during its dispose(). Prior to 1.10, calling the clutter_actor_destroy() function would unmap the actor first, and then emit the destroy signal. This means that extra care should be used when overriding the map() and unmap() virtual functions, to avoid dereferencing NULL pointers. It is also worthy of note that since Clutter 1.8, overriding map() or unmap() is not required any more for subclasses of ClutterActor that have children, as ClutterActor will automatically do the right thing inside its own implementation, and map or unmap its children when needed. • ClutterBox and ClutterGroup have been deprecated. ClutterActor should be used directly, instead. Since ClutterStage inherits from ClutterGroup, the instance and class structures are still available, but subclassing Group is strongly disencouraged. • ClutterContainer provides default implementations for add(), remove(), foreach(), raise(), lower(), and sort_depth_order(); this means that overriding these virtual functions is now deprecated, and developers should only implement ClutterContainer for classes providing child properties. • ClutterActor is not an abstract type any more, and can be instantiated either through clutter_actor_new() or through g_object_new(). • ClutterActor now implements ClutterContainer, and takes over the entire API for modifying the scene graph; this means that every actor can have children and it's not necessary any more to implement the ClutterContainer interface. ClutterActor provides new API to replace clutter_actor_set_parent() and clutter_actor_unparent(), as well as a default implementation of every Container virtual function. Existing actors overriding ClutterContainer and providing an alternate implementation will continue to work, even though it is strongly encouraged to port to the new API. • The ClutterActor::destroy signal is going to be emitted at the beginning of the dispose sequence of a ClutterActor, instead of the end. This allows to access the state of the actor being destroyed, instead of just being able to use its pointer. This may expose bugs in code that does not check for NULL actor pointers. • The long since broken depth cueing support in ClutterStage has been deprecated; the fixed pipeline fog API has been pretty much useless since the switch to colors and textures with premultiplied alpha channels. Setting ClutterStage:use-fog to TRUE has no visible results, and querying the :use-fog and :fog properties will always yield the default values. • ClutterDeformEffect switched from using CoglVertexBuffer to using the CoglPrimitive API internally, to improve performance and use non-deprecated Cogl API. CoglPrimitive converts COGL_WRAP_MODE_AUTOMATIC to COGL_WRAP_MODE_CLAMP_TO_EDGE, unlike CoglVertexBuffer which converts it to COGL_WRAP_MODE_REPEAT. This prevents artifacts when sampling texture coordinates outside the [ 0, 1 ] range. This change may cause the back texture to not be painted if its coordinates go outside the allowed range, for instance when using a custom transformation matrix on the back material used by the ClutterDeformEffect. • The "default stage" has been deprecated; since the 1.0 release, the default stage creation was deferred to the call to clutter_stage_get_default(), and the preferred way for getting a ClutterStage was calling clutter_stage_new() instead. On platforms that do not support multiple stages, attempting to create more than one stage will lead to an error, and Clutter will abort. • Clutter can support multiple backends in the same shared library. Only one windowing or input backend can be used at run time. As a result of this change, the shared library name used by Clutter has changed from: libclutter-<flavour>-<API version>.so to: libclutter-<API version>.so The pkg-config file has been updated accordingly. Until the next major API break, Clutter will ship compatibility links for all the previous "flavours" that were available in versions < 1.10; this allows applications dynamically linking against Clutter, or using dlopen(), to keep working. For libraries and applications dynamically linking against Clutter, though, it is still recommended to recompile to make sure that the most recent version is being used. Language bindings using GObject Introspection will automatically use the new shared library without requiring any change. • The windowing system backend for the CE3100 and CE4100 platforms using the libgdl library is now implemented as a separate backend instance, instead of being a sub-flavour of the EGL native framebuffer backend. This change introduces a new header file, under $includedir/clutter-1.0/clutter/cex100, which should be included to access the CEx100-specific API. The API and ABI of the platform API has not been changed, though it should still be considered experimental. • As of 1.10 it is not necessary any more to call clutter_threads_init() to initialize threading support in Clutter; after the changes in GLib 2.32, threading support in Clutter is always enabled. The rules on how to use Clutter from multiple threads haven't changed. • Deprecated API is now marked using the CLUTTER_DEPRECATED and the CLUTTER_DEPRECATED_FOR annotations; these two annotations will result in compiler warnings when attempting to use the deprecated API. It is possible to disable deprecation warnings for Clutter by defining the CLUTTER_DISABLE_DEPRECATION_WARNINGS symbol when compiling. The previous deprecation symbol, CLUTTER_DISABLE_DEPRECATED, is only used for macros. • Deprecated functionality has been moved to separate header files, installed under the $includedir/clutter-1.0/clutter/deprecated directory. These files are still included by default by clutter/clutter.h. Release Notes for Clutter 1.8 ------------------------------------------------------------------------------- • Cogl has been split out of tree. Clutter depends on Cogl, so users should not notice anything. Developers using pkg-config will gain an extra Cogl dependency. • The clutter_actor_get_gid() and clutter_get_actor_by_gid() functions have been deprecated. They should not have been public in the first place. • ClutterShader and its relative API have been deprecated. ClutterShaderEffect and the effect API is the proper way to use GLSL shaders with ClutterActors. It is possible to instantiate a ClutterShaderEffect directly. • ClutterText's paint volume has been implemented using the ink rectangle of the PangoLayout used to paint, to allow culling to work properly even in the case of glyphs spilling outside the logical rectangle. • Non fully opaque children of a non fully opaque actor will be composited in an offscreen framebuffer object to preserve the correct overall opacity. This changes the way non fully opaque actors are drawn, and might cause some code relying on the old, unspecified behaviour to produce different results. • ClutterBoxLayout layout algorithm has been changed to map the more mature and more stable GtkBox one. • The ClutterText:editable property was incorrectly defined in the GParamSpec as being TRUE by default, but it was initialized to FALSE. To avoid breaking existing code, the default value inside the GParamSpec (and inside the documentation) has been changed to FALSE as well. • The preferred way to draw inside a ClutterCairoTexture is connecting to its ::draw signal, and calling the invalidate() method. The old pattern of creating the Cairo context using the create() method is deprecated but still working as intended. • ClutterScore has been deprecated; the preferred way to chain up multiple animations is to use the ClutterAnimator or ClutterState classes. Release Notes for Clutter 1.6 ------------------------------------------------------------------------------- • The internal copy of JSON-GLib has been removed: Clutter now strictly depends on the installed copy of this library. The --with-json configure switch has been removed. • The ClutterBehaviour class and its sub-classes have been deprecated; the Clutter API reference contains a migration guide to port code based on behaviours to the implicit animations framework. • The ClutterTimeoutPool and clutter_frame_source_* API have been deprecated; both API are not integrated in the Clutter main loop, and are not used internally any longer, so they are of relative use. • It it not necessary any more to provide implementations for the ClutterActor::map() and ClutterActor::unmap() virtual functions, even for composite actors not implementing the ClutterContainer interface. • ClutterTimeline now guarantees that the ::new-frame signal will be emitted at the beginning of the timeline, as well as guaranteeing that the ::completed signal will be emitted at the end of the timeline. • ClutterActor will check for the enabled property of ClutterActorMeta instances (actions, constraints and effects), and will not invoke ClutterActorMeta functions on disabled instances. This removes the requirement for checking the property inside the ClutterActorMeta sub-classes. • ClutterActorBox, ClutterGeometry and ClutterVertex install a progress function for ClutterInterval, allowing the interpolation of properties using them as storage types. • ClutterColor's clutter_color_from_string() function accepts CSS3 color specifications. • The previously unused "axes" field in the ClutterButtonEvent, ClutterScrollEvent and ClutterMotionEvent structures is now used on the X11-based backends with XInput support. • ClutterListModel will honour the filter function when calling clutter_model_get_iter_at_row(). • ClutterClickAction does not use a pointer grab any longer, and uses a capture on the stage instead. • On all platforms which allow it, ClutterStage will ask the windowing system for an explicit key focus when showing the stage window. This can be disabled using clutter_stage_set_accept_focus(). Release Notes for Cogl 1.6 ------------------------------------------------------------------------------- • Cogl may internally optimise cogl_read_pixels when only a single pixel is drawn and the entire scene is comprised of solid colour rectangles. Instead of actually rendering the rectangles it will compute the single pixel value in software. This effectively means that Clutter can do software picking without any API changes. • Internally Cogl now has a GLSL backend as well as the ARBfp and fixed function backends. By default, this backend has the lowest priority but it can be explicitly enabled by setting the COGL_DEBUG environment variable, e.g.: export COGL_DEBUG=disable-fixed,disable-arbfp for builds of Clutter with debug support enabled. • Cogl will internally now cache generated ARBfp programs so that it should be able to reuse a previous program even if it was generated for an unrelated CoglMaterial. This makes using one-shot materials less expensive than before although it is still not recommended. Release Notes for Clutter 1.4 ------------------------------------------------------------------------------- • ClutterLayoutManager sub-classes overriding the set_container() virtual function should chain up to the parent class's implementation. • The ClutterTexture:filename property is now readable, as well as writable; this allows querying the Texture for the filename storing the image data. The value will be unset when using the set_from_*_data() family of functions. • If both the :sync-size and the :keep-aspect-ratio properties of a ClutterTexture are set to TRUE, then the texture actor will update its ClutterActor:request-mode property depending on the orientation of the image data - height-for-width for landscape, and width-for-height for portrait. Square image data will default to height-for-width, like all actors. You can still explicitly override the :request-mode value, or you can unset the :sync-size property to control the size yourself. • All the key symbol macros have been renamed from CLUTTER_* to CLUTTER_KEY_*. The old names are still available inside the clutter-keysyms-compat.h header, which is included by clutter-keysyms.h unless CLUTTER_DISABLE_DEPRECATED is defined. • The internal copy of json-glib is now deprecated. Building Clutter will default to the system copy and requires an explicit --with-json=internal to override the check. Release Notes for Clutter 1.2 ------------------------------------------------------------------------------- * ClutterStageManager is now publicly available and documented API. * Clutter now depends on the system copy of JSON-GLib, and will fall back to the internal copy only if JSON-GLib is not installed. * ClutterActor:opacity is now defined using GParamSpecUint instead of GParamSpecUchar; the same interval of [ 0, 255 ] applies, and GValue has internal transformation functions for converting between G_TYPE_UINT and G_TYPE_UCHAR, so this change should be fully transparent to the user of the code. * On X11 Clutter will emulate XKB's detectable key auto-repeat; this means that when holding down a key, Clutter will emit multiple CLUTTER_KEY_PRESS events and a single CLUTTER_KEY_RELEASE event instead of a list of CLUTTER_KEY_PRESS and CLUTTER_KEY_RELEASE pairs. * On X11 and Win32 the default Stage is created when clutter_stage_get_default() is called for the first time, and not as part of the stage initialization. Cogl API changes for Clutter 1.2 ------------------------------------------------------------------------------- * cogl_viewport is now deprecated in favour of cogl_set_viewport which accepts a viewport offset. * cogl_clip_push() is now deprecated and new code should use cogl_clip_push_rectangle() instead. The old API wasn't consistent with other Cogl APIs that specify model space rectangles using (x0,y0)(x1,y1) pairs. * cogl_clip_push_window_rect() is now deprecated and new code should use cogl_clip_push_window_rectangle(). The old API shouldn't have been defined to take floats and the abbreviation wasn't consistent with other Cogl API. * cogl_clip_stack_save() and cogl_clip_stack_restore() are deprecated, as the functionality is redundant now that offscreen draw buffers own their clip state and switching to/from offscreen rendering will automatically save and restore the clip state. * cogl_material_copy() was added. It is advised that developers use this instead of cogl_material_new() when creating a material that is in some way derived from another. This will allow Cogl to track material ancestries/similarities and reduce the cost of GPU state changes. * cogl_push_draw_buffer, cogl_set_draw_buffer and cogl_pop_draw_buffer are now deprecated and new code should use the cogl_framebuffer_* API instead. Code that previously did: cogl_push_draw_buffer (); cogl_set_draw_buffer (COGL_OFFSCREEN_BUFFER, buffer); /* draw */ cogl_pop_draw_buffer (); can now be re-written as: cogl_push_framebuffer (buffer); /* draw */ cogl_pop_framebuffer (); * All cogl_<type>_ref() and cogl_<type>_unref() functions have been deprecated, and superceded by cogl_handle_ref() and cogl_handle_unref() respectively. * The cogl_check_extension() function has been deprecated. This function was never meant to be public, since it depends on calling glGetString() before its invocation. Users of this function can be replaced by the equivalent code: gl_ext = glGetString (GL_EXTENSIONS); - has_ext = cogl_check_extension (ext_name, gl_ext); + has_ext = strstr (gl_ext, ext_name) != NULL ? TRUE : FALSE; Release Notes for Clutter 1.0 ------------------------------------------------------------------------------- * The clutter_actor_set_shader_param() function now takes a GValue, which can be set using the clutter_value_set_shader() family of functions. The floating point wrapper has been rename clutter_actor_set_shader_param_float() to match the newly added clutter_actor_set_shader_param_int(). * The Pango renderer API has been exposed as public API, after a full rename from PangoClutter to CoglPango, to avoid namespace collisions with upstream Pango. The Pango font map, renderer and glyph cache can be used by third party code and depend only on COGL. * Both Clutter and COGL only allow including <clutter/clutter.h> and <cogl/cogl.h> directly, respectively. This allows avoiding breaking API every time a type definition is moved across headers, and improves the reliability of third party code against internal refactorings. * COGL has an internal Color type, used to store a color definition that can be efficiently used with the least amount of conversions by both the GL and GLES implementations. The COGL API has been changed to drop the usage of ClutterColor in favour of CoglColor. * The fixed point API implementation Clutter uses internally has been moved from the Clutter namespace to the COGL one. * ClutterLabel and ClutterEntry have been removed from the API, as both have been superceded by the ClutterText actor. * ClutterCloneTexture has been removed from the API; in its place, there is a generic ClutterClone actor which allows to "clone" any existing actors -- even composite ones -- without using frame buffer objects (FBOs). * The ClutterEffectTemplate and clutter_effect_* functions have been superceded by ClutterAnimation and thus removed from the public API. * The ClutterBehaviourBspline has been superceded by the usage of ClutterPath inside ClutterBehaviourPath, and thus removed from the public API. * ClutterColor API has received a much needed review to increase its consistency. This has led to the following changes: - clutter_color_parse() has been renamed to clutter_color_from_string() and the order of the arguments has been changed - the factor argument of clutter_color_shade() has been swapped with the return location for the new color - the fixed point entry points have been removed - clutter_color_from_hls() and clutter_color_to_hls() do not normalize the values in the [ 0, 255 ] interval but use the correct HLS intervals: Hue: [ 0, 360 ) Luminance: [ 0, 1 ] Saturation: [ 0, 1 ] * The ClutterFixed symbols have been completely removed: fixed-point public entry points now take a CoglFixed. * The -x and -u API have been removed. All the pixel-based API now takes a float to allow sub-pixel precision; this is true also for properties. WARNING: functions with variadic arguments (like g_object_set(), g_object_get() and clutter_actor_animate()) do not behave very well when dealing with integers instead of expected floating point values, and vice versa. On 32bit machines it will most likely lead to a crash. So: g_object_set (actor, "width", 100, NULL); is incorrect, and should be changed in: g_object_set (actor, "width", 100.0, NULL); * Composite actors that do not implement the Container interface should implement the following virtual functions: - void map (ClutterActor*) - void unmap (ClutterActor*) and chain up to the parent's implementation after calling clutter_actor_map() or clutter_actor_unmap() on their children. * Actors implementing the Container interface that have private children that are not meant to be added/removed through the Container API should implement the: - void foreach_with_internals (ClutterContainer*, ClutterCallback, gpointer); virtual function. * Actors that perform direct transformations using the COGL API inside their paint() implementation should override the apply_transform() virtual function instead. Implementations of the apply_transform() vfunc must chain up to the implementation of the parent class. * The ClutterUnit type and the CLUTTER_UNITS_* conversion macros have been removed: all Actors are now using sub-pixel precision directly throughout the API. The new ClutterUnits type has been added as a generic opaque storage for logical distance values. * Timelines are now fully time-based: all the frame-related properties and methods have been removed. ClutterTimeline::new-frame will provide the elapsed milliseconds since the beginning of the Timeline, instead of the current frame number. The clutter_timeline_new() constructor takes the duration of the timeline in milliseconds, and thus it replaces the clutter_timeline_new_for_duration() variant. Cogl API changes for Clutter 1.0 ------------------------------------------------------------------------------- * All drawing functions now use a source material to determine how geometry is filled. The source material is set via cogl_set_source. Or the convenience functions cogl_set_source_color and cogl_set_source_texture. "drawing functions" include: cogl_rectangle, cogl_texture_rectangle, cogl_texture_multiple_rectangles, cogl_texture_polygon (though the cogl_texture_* funcs have been renamed; see below for details), cogl_path_fill/stroke and cogl_vertex_buffer_draw*. cogl_texture_rectangle, cogl_texture_multiple_rectangles and cogl_texture_polygon no longer take a texture handle; instead the current source material is referenced. The functions have also been renamed to: cogl_rectangle_with_texture_coords, cogl_rectangles_with_texture_coords and cogl_polygon respectively. Most code that previously did: cogl_texture_rectangle (tex_handle, x, y,...); needs to be changed to now do: cogl_set_source_texture (tex_handle); cogl_rectangle_with_texture_coords (x, y,....); In the less likely case where you were blending your source texture with a color like: cogl_set_source_color4ub (r,g,b,a); /* (where r,g,b,a isn't just white) */ cogl_texture_rectangle (tex_handle, x, y,...); you will need your own material to do that: material = cogl_material_new (); cogl_material_set_color4ub (r,g,b,a); cogl_material_set_layer (material, 0, tex_handle)); cogl_set_source_material (material); Code that uses the texture coordinates, 0, 0, 1, 1 don't need to use cogl_rectangle_with_texture_coords since these are the coordinates that cogl_rectangle will use. For cogl_texture_polygon; as well as dropping the texture handle, the n_vertices and vertices arguments were transposed for consistency. So code previously written as: cogl_texture_polygon (tex_handle, 3, verts, TRUE); need to be written as: cogl_set_source_texture (tex_handle); cogl_polygon (verts, 3, TRUE); * The arguments to cogl_rectangle, cogl_path_rectangle and cogl_path_round_rectangle have been changed - for consistency - from x, y, width, height, to x1, y1, x2, y2. * A CoglMatrix type and utility API has been added; this is currently used to support describing texture matrices. * cogl_alpha_func has been removed, since this is now controlled using the material API via cogl_material_set_alpha_test_function () * A Cogl Vertex Buffer API has been added that allows you to efficiently manage arrays of vertex attributes in buffers that may be stored on the GPU. These allow you to avoid the costs of repeatedy validating vertex data and mapping it into the GPU. * cogl_scale now supports scaling on the z axis * cogl_clip_set* and cogl_clip_unset have been renamed to cogl_clip_push and cogl_clip_pop respectively so they self document their stacking semantics. * cogl_paint_init was renamed to cogl_clear and no longer disables lighting and fogging. cogl_clear also now takes a mask of the auxiliary buffers you want to clear so you can avoid redundant clears of buffers you aren't using. * cogl_fog_set was renamed to cogl_set_fog and it now takes a mode argument giving control over the fogging blend factor equation, so that the density argument isn't just ignored. A cogl_disable_fog function was also added. * cogl_get_*_matrix were changed to use the CoglMatrix type instead of GLfloat m[16] arrays. * cogl_offscreen_blit_region, cogl_offscreen_blit were removed since they were only implemnted for GL, not GLES, and it was assumed no one was using them. * cogl_offscreen_new_multisample was removed since it only ever returned COGL_INVALID_HANDLE so it wasn't usefull. * The COGL_MASK_BUFFER type was removed, since there should be nicer ways of exposing color mask if anyone wants it later. It was assumed that no one was using this currently. * COGLenum, COGLint and COGLuint which were simply typedefs for GL{enum,int,uint} have been removed from the API and replaced with specialised enum typedefs, int and unsigned int. These were causing problems for generating bindings and also considered poor style. * The cogl texture filter defines CGL_NEAREST and CGL_LINEAR etc are now replaced by a namespaced typedef 'CoglTextureFilter' so they should be replaced with COGL_TEXTURE_FILTER_NEAREST and COGL_TEXTURE_FILTER_LINEAR etc. * The shader type defines CGL_VERTEX_SHADER and CGL_FRAGMENT_SHADER are handled by a CoglShaderType typedef and should be replaced with COGL_SHADER_TYPE_VERTEX and COGL_SHADER_TYPE_FRAGMENT. * cogl_shader_get_parameteriv has been replaced by cogl_shader_get_type and cogl_shader_is_compiled. More getters can be added later if desired. * cogl_enable_depth_test has been renamed to cogl_set_depth_test_enabled and a corresponding cogl_get_depth_test_enabled function has been added. Release Notes for Clutter 0.8 ------------------------------------------------------------------------------- * The COGL GL wrapper API has been completely overhauled and now contains many new features including new greatly improved texture abstractions (slicing, mipmapping, deformations etc, greatly simplifying ClutterTexture), image loading and abstraction, path based primitive drawing, clipping, and improved FBO and shader support. It is now also fully documented. * GL Texture Rectangle ext is no longer used, the regular 2D NPOTS extension is preffered instead but not required. * Clutter now has basic suppport for multiple input devices assuming the backend supports it (currently X11 based via XInput and Fruity backends). New API supporting this includes clutter_event_get_device_id, clutter_get_input_device_for_id, clutter_grab_pointer_for_device & clutter_ungrab_pointer_for_device. XInput support needs to be explicitly enabled at runtime by calling clutter_x11_enable_xinput () before clutter_init. clutter_x11_has_xinput () can then be called after to check if XInput extension present and use-able. * The functions that return the transformed position of an actor have been renamed to be more explicit about it: clutter_actor_get_abs_position - clutter_actor_get_transformed_position clutter_actor_get_abs_size - clutter_actor_get_transformed_size Their behaviour has not been changed. * To increase portability, Clutter does not strictly depend on GdkPixbuf anymore; this means that you will have to include <gdk-pixbuf/gdk-pixbuf.h> yourself if you are operating with GdkPixbuf objects and not including that header. The GdkPixbuf-based API has been removed from Clutter core: clutter_texture_new_from_pixbuf clutter_texture_set_pixbuf clutter_texture_get_pixbuf are all deprecated functions. It is still possible to load a GdkPixbuf into a ClutterTexture with this sample code: clutter_texture_set_from_rgb_data (texture, gdk_pixbuf_get_pixels (pixbuf), gdk_pixbuf_get_has_alpha (pixbuf), gdk_pixbuf_get_width (pixbuf), gdk_pixbuf_get_height (pixbuf), gdk_pixbuf_get_rowstride (pixbuf), gdk_pixbuf_get_has_alpha (pixbuf) ? 4 : 3, 0, &error); ClutterTexture also now has a new filename property and clutter_texture_new_from_file which is intended as an alternate to common previous GdkPixbuf primary usage (i.e loading images from disk). To read texture data back into a pixbuf or system memory use a combination of clutter_texture_get_cogl_texture & cogl_texture_get_data. The clutter-gtk integration library has API for using GdkPixbuf with ClutterTextures (among others). ClutterTexture now supports a keep-aspect property which is set to FALSE by default. * clutter_texture_from_actor will now reparent source actors if they are not parented. This behaviour may change in future releases. There are known not yet fixed issues with source actors that set depth or use clipping. * The size negotiation API has been completely changed in order to allow the creation of non-fixed layout managers. These functions have been removed: clutter_actor_request_coords() clutter_actor_query_coords() from the ClutterActor API, as well as their virtual functions inside the ClutterActorClass. The size of an actor is now split into two different concepts: the preferred size (width and height separatedly) and the size that has been allocated by the container to which that actor belongs. Clutter still defaults to the fixed layout management (i.e ClutterGroup) of the actors, but supports fluid layout managers written using the new API. Composite actors (actors with 'private' children not implementing the container interface) now need to implement an allocate method here pass an allocation to any composite children. * Clutter now depends on PangoCairo for the font rendering. The PangoClutter API is still considered semi-private and no guarantees are made on its stability. * ClutterShader API has been slightly changed: the ClutterStage:bound property, clutter_shader_bind() and clutter_shader_is_bound() have been renamed to :compiled, clutter_shader_compile() and clutter_shader_is_compiled(), respectively. The previously semi-private clutter_shader_release_all() function is now not exported anymore. * ClutterStage is not an abstract type anymore: it can be instantiated using clutter_stage_new() and it can be properly subclassed. If the backend supports multiple stages, every stage will be a new window, whose lifetime will have to be managed by the developer. Clutter will still create the default stage, and guarantees that every call to clutter_stage_get_default() will return exactly the same pointer. * Actors now have a new 'show-on-set-parent' property set to TRUE by default. With this property set to TRUE, actors will automatically have clutter_actor_show() called on them when a parent is set (i.e added to a container). * Clutter now features support for multiple stages assuming supported by the backend. See test-multistage.c for example of usage. This does not change the automatic creation of the default stage. A single GL context is used across all stages meaning GL resources are shared. * There is now an experimental native iPod Touch/iPhone UIKit backend named 'fruity'. * There is now an experimental native Win32 WGL backend. * COGL (and therefor Clutter) now optionally features initial support for OpenGL ES 2.0. It features support for shaders. * Some more focused timeline unit tests have been added and some tweaks to timeline semantics were made; E.g. For a 10 frame timeline here are some points about the semantics: - When you create a timeline it starts with current_frame_num == 0 - After starting a timeline, the first timeout is for current_frame_num == 1 (Notably it isn't 0 since there is a delay before the first timeout signals so re-asserting the starting frame (0) wouldn't make sense.) - For a non looping timeline the last timeout would be for current_frame_num == 10 - For a looping timeline the timeout for current_frame_num == 10 would be followed by a timeout for current_frame_num == 1 and frame 0 is considered == frame 10. - Asking for a timeline of N frames might better be described as asking for a timeline of _length_ N. * The behaviour of clutter_actor_get_opacity() has been slightly changed; instead of returning the composited opacity of the entire parents chain of an actor, clutter_actor_get_opacity() does what you mean, and returns the opacity set with clutter_actor_set_opacity(). The composited opacity value is now returned by clutter_actor_get_paint_opacity(). * Until 0.6, clutter_label_get_color() would have returned a ClutterColor with the alpha component equal to the composited opacity of the label. Now, clutter_label_get_color() returns a copy of the exact color set with clutter_label_set_color(). * The ClutterEntry actor will automatically handle key events inside a key-press-event handler. This deprecates the usage of clutter_entry_handle_key_event() to update the contents of the entry using the ClutterKeyEvent. * The Clutter X11 and GLX backends feature support for wrapping external X Drawables (such as windows as pixmaps) via the 'texture_from_pixmap' GLX extension if available and fallback to slower XGetImage copies if not. * ClutterContainer can have per child custom properties via ClutterChildMeta. Release Notes for Clutter 0.6 ------------------------------------------------------------------------------- * Now that every actor has events, the class signal handlers have been removed from ClutterStageClass and moved into ClutterActorClass. * The CLUTTER_2BUTTON_PRESS and CLUTTER_3BUTTON_PRESS event types have been removed in favour of the ClutterButtonEvent:click_count counter * X11 related called for glx and eglx backends are now shared and moved into a clutter_x11 prefix. * Scaling with gravity functionality was replaced by more generic and powerful anchor point. * The ClutterLayout interface, the ClutterBox and its implementations have been moved outside Clutter core. * The Effects API has been simplified, and it only requires the final value of the effect instead of both the start and end value. * The per-axis rotation API has been deprecated in favour of a single pair of accessors, clutter_actor_set_rotation() and clutter_actor_get_rotation(). * Every actor sub-class that is overriding the ClutterActor::request_coords() virtual function *must* chain up to the parent's implementation in order to store the bounding box inside the ClutterActor private data. * It is now impossible to call clutter_actor_destroy() on the stage. Backends will have to unset the CLUTTER_ACTOR_IS_TOPLEVEL private flag to actually destroy the stage. * The default value of the ClutterLabel:wrap property has been changed from TRUE to FALSE. * All the behaviours properties have been renamed to match the $PROPERTY-start and $PROPERTY-end convention. * The clutter_group_add() function has been "undeprecated" and reimplemented as a commodity macro; a clutter_stage_add() commodity macro has also been added. Both macros just safely wrap clutter_container_add_actor(). * The ClutterContainer::find_child_by_id() virtual function has been removed; Clutter keeps track of every actor, so there's no need to recurse into containers anymore. * The unused ClutterActor::set_depth() and ClutterActor::get_depth() virtual functions have been removed. * It is now possible to roundtrip the string created by clutter_color_to_string() to clutter_color_parse(). * The amount of motion events is now being throttled using the default frame rate setting as the base value to compute the default and maximum frequency of motion events to be delivered to every actor. * ClutterAngle usage has been removed from the public API: it is an internal optimization, which can be used for faster angle computations; users of ClutterAngle now take a fixed point number in form of a ClutterFixed. * ClutterGravity usage when scaling has been superceded by the anchor point. * The precision of the clutter_sqrti() algorithm has been improved for small values. * ClutterBehaviourScale constructor, scale properties and accessors have been changed to accomodate the scaling factors on both the X and Y axis, matching the clutter_actor_set_scale() function. This also changed the clutter_effect_scale() function, which now accepts the final scale factor on both the X and Y axis. The gravity property has also been removed, as it behaved incorrectly with regards to the anchor point. When scaling an actor using a BehaviourScale, the anchor point should be set before applying the behaviour (remember to adjust the positioning as well by factoring in the anchor point). * The clutter_do_event() is now public; it can be used to feed an event to Clutter and let it generate the capture-bubble signal emissions; it should not be used by applications. * In the X11-based backends, the DestroyNotify event is not propagated to Clutter core if the stage is using a foreign window. * To avoid method name collisions between ClutterActor and ClutterEntry in high-level languages, the clutter_entry_set_position() and clutter_entry_get_position() functions have been renamed to clutter_entry_set_cursor_position() and clutter_entry_get_cursor_position() respectively. Release Notes for Clutter 0.4.0 ------------------------------------------------------------------------------- * clutter_actor_show_all does not recurse for groups at least (this is to match the original group_show_all behaviour). This is like 0.3 but was never noted. * ClutterBox API has changed: clutter_box_pack_start() and clutter_box_pack_end() have been removed in favour of the clutter_box_pack() API. * Both clutter_threads_enter() and clutter_threads_leave() have been removed from the API, as they just created confusion and the wrong idea that Clutter is either thread-safe or thread-aware. Full thread-awareness is arriving in the next revision (see bug #429). * The ClutterBehaviourRotate and ClutterBehaviourEllsipse APIs have been overhauled. Release Notes for Clutter 0.3.1 ------------------------------------------------------------------------------- * clutter_actor_apply_transform_to_point() parameters changed to use ClutterVertices. * New 'Native API' backend expects EGL implementation to provide a CreateNativeWindow() API call. * Exisiting X11 based egl backend public API calls now prefixed eglx. Release Notes for Clutter 0.3 ------------------------------------------------------------------------------- * ClutterTexture changes: + clutter_texture_set_pixbuf() now takes a GError paremeter. + clutter_texture_upload_data has been split into two new and more functional versions; clutter_texture_set_from_rgb_data(), clutter_texture_set_from_yuv_data(). * The GLX specific API has been moved to the GLX backend code and it's now under the ClutterGlx namespace. * The priority of the various users of the GLib main loop has been reviewed and changed were necessary. Every paint is queued with a priority of G_PRIORITY_DEFAULT + 10; timelines are allocated with a G_PRIORITY_DEFAULT + 30 priority; events are processed with a G_PRIORITY_DEFAULT priority. This ensures that events are processed before the paints take place. * The ClutterActor::allocate_coords() has been renamed to ClutterActor::query_coords(), in order to clarify its usage. * Actors overriding ClutterActor::request_coords() and ClutterActor::query_coords() must convert sizes obtained from the public API from pixels to ClutterUnits, using the conversion macros found in clutter-units.h. The conversion will be necessary until the public API will switch over to returning the generic units too. * Users of Intel video cards should find that disabling sync-to-vblank is no longer necessary. In case Clutter applications take really long times for redrawing and appear stuck and unresponsive, the sync-to-vblank feature might still be the culprit; in that case, use "export CLUTTER_VBLANK=none" to disable it and file a bug reporting the video card model, the driver version and the X server version. * ClutterTimeline objects now share the same timeout pool (see the ClutterTimeoutPool API). This might cause problems with heavily threaded libraries without integration with the GLib main loop. If an application experiences bad behaviours during animations use "export CLUTTER_TIMELINE=no-pool" to disable the timeout pool. * clutter_color_parse() now handles color definitions with alpha. Alpha will default to fully Opaque rather than fully transparent if not specified. * The Clutter examples/ directory has been removed and replaced with a tests/ directory. * The ClutterEvent API has been changed, and specific functions have been removed in favour of event-agnostic ones. * The ClutterStage::input-event signal has been removed. All the events now emit the ClutterStage::event and ClutterStage::event-after signals, for generic event handling. * Runtime options now dependant on backend. * ClutterGroup API to add, remove and list children has been deprecated in favour of ClutterContainer API. The ClutterGroup::add and ClutterGroup::remove signals have been deprecated: ClutterContainer::actor-added and ClutterContainer::actor-removed should be used instead.